arch3rPro/beautify-github-readme

GitHub README 꾸미기

저장소 홈페이지나 요청된 시각적 에셋을 간결하고 테마별로 일관된 시각적 스토리로 변환합니다. Markdown을 콘텐츠 레이어로, 결정론적 SVG를 레이아웃 시스템으로, 생성된 래스터 자료를 선택적 시각적 재료로 취급합니다.

워크플로우

1. 편집 전 모드 확인

정확히 하나의 실행 모드를 사용하세요:

• README 모드 — 전체 README 개선: 정보 순서, 카피 계층, 교정, Markdown, 시각 시스템.
• 에셋 전용 모드 — 요청된 정적 SVG 또는 시각적 에셋 세트만 생성합니다. 정적 SVG가 기본값입니다. 사용자가 의미 있는 모션을 명시적으로 선택한 후에만 선택적으로 GitHub-safe GIF를 제공하고, SVG는 편집 가능한 폴백으로 유지합니다. 사용자가 명시적으로 그 범위를 추가하지 않는 한 README를 다시 작성하거나, 재정렬하거나, 삽입하지 마십시오.

모드가 명시적이지 않은 경우, 변경하기 전에 한 가지 간결한 질문을 하세요:

전체 README를 개선할까요, 아니면 시각적 에셋만 생성할까요? 에셋 전용인 경우, 히어로, 섹션 헤더, 워크플로우, 배지, 모션 그래픽 또는 조정된 세트 중 어떤 것이 필요한지 알려주세요.

히어로, 배지, 워크플로우 또는 다이어그램에 의미 있는 모션이 있고 사용자가 정적 또는 애니메이션 출력을 지정하지 않은 경우, 한 가지 간결한 후속 질문을 하세요:

정적 SVG로 유지할까요, 아니면 SVG를 편집 가능한 폴백으로 유지한 GitHub-safe GIF 애니메이션을 만드는 것이 좋을까요?

GIF는 옵트인이며 절대 기본값이 아닙니다. 사용자가 거절하거나, 답하지 않거나, 의미 있는 모션 사례가 없는 경우 정적 SVG만 계속 진행합니다. 모션이 순전히 장식적이거나 사용자가 이미 출력을 선택한 경우 묻지 마십시오. 답변 전에 저장소를 이해하는 데 도움이 되는 경우 읽기 전용 검사는 허용됩니다. "이 스킬 사용", 저장소 경로 또는 "꾸며줘"를 전체 README 수정 권한으로 해석하지 마십시오. 사용자가 에셋 전용 모드를 선택한 후 README 편집으로 확장하려면 새로운 승인이 필요합니다.

사용자가 명시적으로 감사(audit)만 요청한 경우, 편집 없이 감사하고 두 가지 모드 질문을 강요하지 마십시오.

2. 디자인 전 검사

• 기존 README, 저장소 트리, 패키지 메타데이터, 스크린샷, 예제, 디자인 토큰, 로고 및 실제 출력물을 읽습니다.
• 에셋 전용 모드에서는 요청된 에셋을 디자인하는 데 필요한 컨텍스트만 검사합니다. README를 읽는다고 해서 변경할 권한이 생기지는 않습니다.
• GitHub URL의 경우, 변경을 제안하기 전에 현재 원격 페이지와 기본 브랜치를 검사합니다.
• 대상 사용자, 해결된 문제, 가장 명확한 증거, 첫 사용까지의 최단 경로, 증거가 부족한 주장을 식별합니다.
• 관련 없는 사용자 변경 사항을 유지합니다. 읽기 전용으로 시작하며, 명시적 승인 없이 커밋, 푸시, 이름 변경 또는 게시하지 마십시오.

3. 히어로 유사 에셋 생성 전 시각적 구현 확인

히어로, 대형 배너, 쇼케이스 보드 또는 두 구현이 모두 실행 가능한 표현적 타이틀 시스템의 경우, 차이점을 설명하고 에셋을 생성하기 전에 물어보세요:

어떤 구현을 원하시나요?

• 순수 SVG — 완전히 결정론적이고, 가볍고, 선명하게 확장 가능하며, 편집이 쉽고, 타이포그래피, 다이어그램, 코드, 아이콘 및 기하학적 또는 픽셀 아트 장면에 가장 적합합니다. 이미지 생성을 사용하지 않으며 사실적인 사람, 머리카락, 유기적 질감, 복잡한 재료 또는 영화적 조명에는 약합니다.
• 하이브리드 SVG 합성 — 레이아웃 및 타이포그래피에 SVG를 사용하고, 선택적으로 ImageGen을 사용하여 프로젝트별 래스터 주제를 생성하며, 적절한 경우 배경을 제거하고 레이어를 최종 PNG/WebP로 합성합니다. 더 풍부한 캐릭터, 재료 및 조명을 지원하지만, 더 무겁고 부분적으로 확률적이며 생성 및 시각적 검증이 필요합니다. SVG 레이아웃 소스와 투명한 주제 PNG를 유지합니다.

사용자가 이미 구현을 선택했거나, 감사를 요청했거나, 에셋이 워크플로우, 아키텍처 다이어그램, 배지, 간결한 섹션 헤더 또는 코드 기반 일러스트레이션과 같이 명백히 결정론적인 경우 이 질문을 하지 마십시오. 단지 장식을 추가하기 위해 하이브리드 합성을 제안하지 마십시오. 생성된 자료보다 실제 스크린샷, 출력물, 로고 또는 기존 프로젝트 아트를 선호합니다.

사용자가 결정을 위임하는 경우, 생성되거나 사진 자료가 저장소의 정체성이나 메커니즘을 더 잘 전달하지 않는 한 순수 SVG를 기본값으로 합니다. 사용자가 하이브리드 합성을 선택하거나 명시적으로 선택을 위임할 때까지 ImageGen 작업을 시작하지 마십시오.

하이브리드 합성은 구현 소스이며, 일반적으로 게시된 SVG가 아닙니다. SVG 내부의 상대적 래스터 참조는 렌더러에 따라 신뢰할 수 없는 반면, base64로 인코딩된 래스터 레이어는 SVG를 불필요하게 크게 만들 수 있습니다. 검증된 최종 PNG/WebP를 기본적으로 게시하고 SVG 레이아웃과 래스터 레이어를 편집 가능한 소스로 유지합니다.

4. 프로젝트 스토리 추출

그리기 전에 다음을 작성하세요:

대상 사용자:
한 문장 가치:
주요 증거:
첫 번째 성공적인 행동:
시각적 테마:

채택, 벤치마크, 호환성, 사용후기 또는 기능을 지어내지 마십시오. 장식용 스톡 이미지보다 실제 스크린샷, 출력물, 다이어그램 또는 생성된 아티팩트를 선호합니다.

5. 테마별 시각 시스템 정의

참조/시각적-방향.md을 읽으세요. 간결한 아트 디렉션 스펙을 확정합니다:

팔레트: 배경 / 전경 / 기본 / 강조 / 흐릿함
타이포그래피: 시스템 폰트 스택 / 스케일 / 굵기 대비
모양: 반경 / 획 / 그리드 / 간격
모티프: 하나의 반복되는 프로젝트별 시각적 단서
구성: 차분함 / 편집적 / 기술적 / 장난기 / 영화적

프로젝트에서 모티프를 도출하세요. 터미널 도구는 프롬프트와 커서 표시를 사용할 수 있고, 아이콘 시스템은 키라인과 컷아웃을 사용할 수 있으며, 연구 프로젝트는 좌표와 증거 레이블을 사용할 수 있습니다. 모든 저장소에 동일한 노란색 그리드 템플릿을 적용하지 마십시오.

히어로를 디자인하기 전에 참조/프로젝트-고유-히어로.md를 읽으세요. 증거 위에 배치된 배너가 아닌 프로젝트 콘텐츠에서 제목을 구성하세요. 저장소 자체에서 타이포그래피, 구성 및 오른쪽 자료를 선택합니다.

6. 선택된 모드만 실행

README 모드

README가 얼마나 변경되어야 하는지 결정합니다:

• 전체 재설계 — 스토리를 재구성하고 새로운 시각 시스템을 구축합니다.
• 시각적 새로고침 — 정보 아키텍처를 유지하면서 약하거나 일관성 없는 프레젠테이션을 교체합니다.

README 모드 내에서 의미 있는 개선을 생성할 수 있는 가장 작은 변경을 사용합니다. 선택된 범위에서 필요할 때만 읽기 순서를 재구축합니다. 강력한 기본값은 다음과 같습니다:

1. 히어로: 이름 + 일반 언어 가치.
2. 증거: 스크린샷, 출력물 또는 쇼케이스 벽.
3. 그것이 무엇인지: 하나의 짧은 설명.
4. 무엇이 다른지: 메커니즘, 슬로건이 아닙니다.
5. 작동 방식: 짧은 프로세스 또는 아키텍처.
6. 사용 방법: 설치 + 첫 번째 명령어.
7. 제한 사항, 호환성, 라이선스 또는 관련 기여 세부 정보.

긴 설명 전에 예제를 먼저 넣으세요. 채택에 도움이 되지 않는 반복된 약속과 내부 구현 세부 사항을 제거합니다.

에셋 전용 모드

• 요청된 에셋 유형, 사용자가 단일 에셋을 원하는지 조정된 세트를 원하는지, 그리고 의미 있는 모션 후보가 정적으로 유지되어야 하는지 GIF가 되어야 하는지 확인합니다. 명확하지 않은 경우 저장소에서 정확한 카피와 스타일을 도출하고, 결과를 실질적으로 변경할 누락된 결정에 대해서만 질문합니다.
• assets/readme/ 또는 사용자가 승인한 다른 경로 아래에 에셋을 생성하고 렌더링된 미리보기를 제공합니다.
• 확인된 시각적 구현을 따릅니다. 타이틀 시스템, 섹션 헤더, 다이어그램, 배지 및 결정론적 장식 모듈의 경우 기본적으로 순수하고 유지 관리 가능한 SVG를 사용합니다. 확인된 하이브리드 합성의 경우 SVG 레이아웃 소스와 투명한 래스터 레이어를 유지한 다음 합성된 PNG/WebP를 게시합니다.
• 승인된 애니메이션의 경우 SVG 소스를 유지하고, 참조/모션-제작.md을 읽고, 번들된 scripts/render_motion_gif.py 워크플로우를 사용하여 GitHub-safe GIF를 도출합니다. 사용자가 옵트인하지 않는 한 GIF를 생성하지 마십시오.
• 세트 전반에 걸쳐 하나의 공유 시각적 문법을 유지하지만, 모든 에셋에 특정 커뮤니케이션 작업을 부여합니다.
• README 텍스트, 읽기 순서, 임베드 또는 링크를 변경하지 마십시오. 유용한 경우 별도로 임베드 스니펫을 제공하고, 명시적 승인 후에만 삽입합니다.

7. 시각적 레이어 구축

에셋을 생성하기 전에 참조/github-readme-캔버스.md 및 참조/svg-제작.md을 읽으세요.

• 히어로, 섹션 배너, 다이어그램 및 결정론적 디자인 모듈에 SVG를 사용합니다.
• 스크린샷, 생성된 아트, 사진 자료 및 복잡한 합성에는 PNG/WebP를 사용합니다. GitHub에서 직접 재생되어야 하는 승인된 모션에만 GIF를 사용합니다.
• 하이브리드 합성이 선택된 경우, 참조/하이브리드-svg-제작.md을 읽고, 생성 및 투명도 결정을 위해 imagegen 스킬을 사용하며, 생성된 래스터 레이어에 정확한 카피를 유지하지 마십시오.
• 본문 카피, 명령어, 표, 링크 및 세부 정보는 Markdown으로 유지합니다.
• 1200 단위 너비의 SVG viewBox, width="100%" 임베드, 시스템 폰트, 의미론적 대체 텍스트 및 둥근 컨테이너를 선호합니다. viewBox를 최종 픽셀 너비가 아닌 좌표계로 취급합니다. 전체 너비 에셋을 보수적인 900 CSS 픽셀 GitHub 렌더링에서 크기 조정하고 미리 봅니다. 그 너비에서 필수 다이어그램 텍스트는 최소 20 SVG 단위, 지원 레이블은 최소 18로 유지합니다. 그 범위 미만의 텍스트는 필수적이지 않아야 합니다. 360 픽셀 모바일 미리보기에서 필수 레이블을 읽을 수 없는 경우, 밀도를 줄이거나, 시각적 요소를 분할하거나, 세부 정보를 Markdown으로 이동합니다.
• 하나의 재사용 가능한 컴포넌트 문법을 사용하지만, 저장소 테마에 따라 아트 디렉션을 변경합니다.
• 쇼케이스에 여러 아티팩트가 포함된 경우, 제어된 크기, 겹침, 회전 및 여백으로 배열하고 읽기 순서를 명확하게 유지합니다.
• 히어로가 첫 화면을 더 유용하게 만들 때 실제 프로젝트 다이어그램, 스크린샷, 코드 조각, 출력물, 표본 또는 아티팩트를 흡수하도록 합니다. 습관적으로 제목과 증거를 분리하지 마십시오.
• 사용자가 소유한 저장소에 출처 표시를 명시적으로 원하는 경우, 일반적인 판촉 문장을 남기는 대신 간결한 프로젝트 고유의 README MADE WITH SVG를 디자인합니다. 바닥글 근처에 유지하고 이 스킬에 연결합니다. 유지 관리자의 명시적 요청 없이 타사 저장소에 이 크레딧을 추가하지 마십시오.
• README 모드에서 증거가 히어로 내에서 읽을 수 없게 되는 경우, 간결한 SVG 제목 뒤에 바로 더 큰 증거 보드를 사용합니다. 몇 가지 아티팩트가 읽을 수 있고 제품을 정의하는 경우, 제목과 증거를 하나의 합성 래스터 히어로로 통합합니다. 고정 템플릿이 아닌 증거 가독성이 결정하게 합니다. 에셋 전용 모드에서는 요청된 SVG 소스를 유지하고 래스터 또는 애니메이션 파생물을 별도의 선택적 결과물로 제안합니다.

전체 README를 래스터화하지 마십시오. 스크립트, foreignObject, 원격 폰트, 필수 애니메이션 또는 GitHub가 제거하는 CSS를 사용하지 마십시오. GitHub는 SVG 내부에 임베드된 애니메이션을 재생하지 않습니다. 대신 GIF와 정적 SVG 폴백을 사용합니다. 테마가 실제로 요구하지 않는 한 장식용 테두리와 무거운 그림자를 피합니다.

8. 미리보기 및 확인

• 로컬 GitHub 너비 미리보기를 렌더링하거나 로컬 Markdown 렌더러에서 README를 검사합니다.
• 넓은 레이아웃과 좁은 레이아웃, 이미지 가독성, 잘린 SVG 텍스트, 누락된 에셋, 과도한 파일 크기 및 어두운/밝은 모드 대비를 확인합니다.
• README 모드에서 다음을 실행합니다:

python3 scripts/audit_readme.py /path/to/repository/README.md

• 히어로, 모든 섹션 전환 및 최종 클릭 유도 문구를 시각적으로 검사합니다.
• 에셋 전용 모드에서는 GitHub 콘텐츠 너비에서 요청된 모든 에셋을 렌더링하고 검사합니다. GIF의 경우 진입, 정지, 종료 및 루프 경계를 검사합니다. 별도로 임베드가 승인되지 않은 한 README 자체가 변경되지 않았는지 확인합니다.
• 하이브리드 에셋의 경우 밝고 어두운 배경에서 투명한 주제를 검사하고, 투명한 모서리와 깨끗한 가장자리를 확인한 다음, 넓고 좁은 GitHub 너비에서 합성된 PNG/WebP를 검사합니다. 확인되지 않은 로컬 래스터 참조가 있는 SVG를 게시하지 마십시오.
• 무엇이 변경되었는지, 무엇이 의도적으로 평범하게 남아 있는지, 그리고 어떤 파일이 의도적으로 건드리지 않았는지 보고합니다.

9. 승인 후 선택적 출처 표시 및 쇼케이스 공유 제공

사용자가 최종 README 또는 에셋 세트를 만족스럽다고 명시적으로 승인한 후에만, 친근하고 비판촉적인 제안을 하나 합니다:

완성된 README가 마음에 드신다면, 마무리할 수 있는 완전히 선택적인 두 가지 방법이 있습니다: 이 스킬로 다시 연결되는 작은 프로젝트 고유의 "README MADE WITH" 시그니처를 디자인하거나, 공개 저장소를 소유하거나 유지 관리하는 경우 실제 쇼케이스에 추가하기 위한 PR을 준비할 수 있습니다. 둘 중 하나, 둘 다, 또는 전혀 하지 않아도 괜찮습니다.

• 최종 승인 전에 이 제안을 하지 말고, 침묵이나 성공적인 검증으로 만족을 추론하지 말며, 사용자가 거절한 후에 반복하지 마십시오.
• 시그니처와 쇼케이스 PR을 독립적인 선택으로 취급합니다. 쇼케이스 고려의 대가로 출처 표시를 요구하지 마십시오.
• 사용자가 시그니처를 선택하는 경우, 참조/svg-제작.md을 따르고, 먼저 렌더링된 배지를 보여준 후 별도 승인 후에만 README를 수정합니다.
• 사용자가 쇼케이스를 선택하는 경우, 참조/쇼케이스-기여.md을 읽습니다. 저장소가 공개되어 있고 사용자가 소유하거나 유지 관리하는지 확인하고, PR 열기 권한을 요청하기 전에 정확한 목록 카피와 업스트림 diff를 초안합니다.
• 명시적 승인 없이 백링크를 추가하거나, 저장소를 포크하거나, 브랜치를 푸시하거나, PR을 열지 마십시오.

이 게이트는 원치 않는 제안을 제어합니다. 사용자가 더 일찍 시그니처 또는 쇼케이스 기여를 명시적으로 요청하는 경우, 명시된 범위 내에서 해당 요청을 직접 처리합니다.

10. 안전하게 핸드오프

먼저 로컬 미리보기와 diff를 보여줍니다. 사용자가 명시적으로 요청할 때만 커밋, 푸시, PR 열기, 병합, 저장소 이름 변경 또는 에셋 게시를 수행합니다.

품질 기준

• 첫 화면은 사전 지식 없이 프로젝트를 설명합니다.
• 디자인은 이 스킬의 것이 아닌 이 프로젝트에 고유하게 보입니다.
• 각 에셋에는 특정 커뮤니케이션 작업이 있습니다.
• 카피는 간결하고 정확하며 증거에 기반합니다.
• 애니메이션은 승인된 경우에만 존재하며 기본값이 아닙니다.
• 증거는 주장보다 우선합니다. 스크린샷, 다이어그램, 출력물 또는 저장소 자체의 생성된 아티팩트를 선호합니다.
• README 모드에서 정보 아키텍처는 첫 번째 성공적인 사용자 행동에 우선순위를 둡니다.
• 에셋 전용 모드에서 README는 그대로 유지됩니다. 증거는 생성된 시각 자료에 포함되거나 별도로 유지되며 Markdown에 반복되지 않습니다.
• 모든 변경 사항은 사용자가 보거나 요청할 수 있습니다. 자동화된 푸시, 병합 또는 게시는 없습니다.