Communitygithub.com

geekjourneyx/readme-generator

GitHub 프로젝트용 포트폴리오 수준의 README.md를 생성합니다. README 작성, 최적화, 이미지 생성 등을 지원합니다.

readme-generator란 무엇인가요?

이 스킬은 AI 에이전트(Claude Code, Cursor, Codex 등)가 GitHub 프로젝트를 분석하여 포트폴리오 수준의 README.md를 생성하도록 돕습니다. README가 프로젝트의 첫인상을 결정한다는 원칙 아래, 단순한 기능 나열이 아닌 명확한 가치 전달, 시각적 표현, 빠른 시작 경로를 중시합니다. 프로젝트 유형(UI/제품, SDK, 도구 등)에 따라 적절한 시각적 전략(Codex Image Gen, HTML to PNG)과 템플릿을 선택하며, 최대 2개의 웹P 이미지(banner.webp, features.webp)를 포함합니다. 또한 GitHub Description, Topics, 라이선스 추천까지 제공하여 프로젝트의 검색 노출과 신뢰도를 높입니다. README 품질을 5가지 기준(15초 이해도, 프로젝트 스토리, 시각적 표현, 빠른 시작, 신뢰성, 절제)으로 평가하여 90점 미만은 재작성하는 엄격한 기준을 적용합니다. 사용자에게 불필요한 질문을 최소화하고 프로젝트 파일에서 직접 정보를 추론하여 효율적으로 작업합니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add geekjourneyx/readme-generator

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

미리보기

스킬 README에서

License: MIT
readme-generator preview
readme-generator preview

문서

GitHub README Generator

README는 프로젝트의 첫 번째 포트폴리오 페이지입니다. 설명서의 목차나 기능 목록의 컨테이너가 아닙니다. 짧은 시간 안에 세 가지 질문에 답해야 합니다:

  1. 이것은 무엇인가.
  2. 왜 볼 가치가 있는가.
  3. 어떻게 사용을 시작하는가.

이 Skill의 목표는 100점 README 작품을 생성하는 것입니다: 명확하고, 미적 감각이 있고, 절제되고, 신뢰할 수 있으며, 프로젝트가 완전한 작품처럼 이해되도록 하는 것입니다.


제일 원리

README는 신뢰의 입구이자 경로의 입구이며, 완전한 문서가 아닙니다. 리포지토리를 처음 열어본 사람이 빠르게 판단할 수 있도록 도와야 합니다:

  1. 이 프로젝트가 어떤 문제를 해결하는가.
  2. 나에게 적합한가.
  3. 즉시 실행, 설치 또는 더 알아볼 수 있는가.

1만 개 이상의 별을 받은 오픈소스 프로젝트는 일반적으로 정보량이 아니라 명확한 첫 화면, 직접적인 시작 경로, 신뢰할 수 있는 문서 입구, 절제된 커뮤니티 정보로 성공합니다. 이미지, 배지, 작성자 정보, 디자인 철학은 모두 보조 수단일 뿐입니다. 이해를 늦추면 노이즈가 됩니다.

이 Skill의 핵심 절충: README는 먼저 프로젝트를 설명하고, 그 다음에 미화합니다. 시각적 요소는 이해를 돕는 역할을 하며, 이해를 대체하지 않습니다.


작품 기준

다음 평가표로 모든 출력을 제한합니다:

차원점수판단 기준
15초 이해25첫 화면에서 프로젝트 이름, 가치, 대상이 보이는가
프로젝트 스토리20기능 나열이 아닌 배경, 동기, 결과를 설명하는가
시각적 표현20이미지가 작품처럼 보이고, 작은 글씨의 흐름도 같지 않은가
빠른 시작15설치 및 사용 경로가 짧고, 명확하며, 복사 가능한가
신뢰할 수 있는 결과물10실제 출력, 능력 경계 또는 결과를 보여주는가
절제 및 노이즈 제거10중복, 구호, 과도한 설명 및 장식을 제거했는가

90점 미만의 README는 전달하지 않습니다. 먼저 노이즈를 제거하고, 핵심을 확대하고, 내러티브를 재구성합니다.

고별 프로젝트 기준

기본적으로 고별 오픈소스 프로젝트의 다음 구조를 따릅니다:

  • 프로젝트 이름 + 한 줄 가치 제안.
  • 필요 최소한의 배지, 상태 장식은 쌓지 않음.
  • 빠른 시작 또는 문서 입구를 앞쪽에 배치.
  • 예제는 시작 비용을 낮출 때만 등장.
  • 기여, 커뮤니티, 보안, 라이선스는 간결하고 명확하게.
  • UI / 제품 프로젝트는 스크린샷을 넣을 수 있음. 라이브러리, SDK, 인프라 도구는 그림이 적거나 없음.

README를 디자인 선언문, 완전한 설명서, 기능 벽, 소셜 명함 또는 내부 워크플로 보고서로 작성하지 마십시오.


디자인 원칙

반드시 지켜야 할 것

  • H1은 프로젝트의 공식 이름이어야 하며, 바로 뒤에 가치 제안이 와야 합니다.
  • README 시작 부분은 먼저 프로젝트 가치를 설명하고, 그 다음 설치 세부 정보를 배치합니다.
  • 이미지는 하나의 핵심만 표현해야 하지만, 프로젝트 명함 역할을 해야 합니다: 독자가 프로젝트 이름과 포지셔닝을 한눈에 볼 수 있어야 합니다.
  • 기본적으로 최대 두 개의 이미지: 하나는 커버, 하나는 핵심 능력 또는 결과 이미지.
  • GitHub는 이미지를 축소하여 표시하므로, 이미지의 주요 텍스트는 포스터 크기로 설계해야 합니다.
  • 기능에 대한 설명은 구체적이어야 하지만 과장되지 않아야 합니다. 결과로 설명할 수 있으면 자화자찬하지 마십시오.
  • 작성자와 라이선스는 간결하게 유지하고, 소셜 명함을 쌓지 마십시오.

반드시 피해야 할 것

  • ASCII 아트 제목.
  • 이모지로 장식된 제목 또는 작성자 표.
  • "우리는 전문가입니다"와 같은 장황한 빈말.
  • 한 이미지에 6개 이상의 작은 카드를 쌓는 것.
  • 흐름도에 단계, 명령, 작은 글씨 설명을 채우는 것.
  • 세 번째 흐름도를 기본 산출물로 간주하는 것. 작업 방식은 일반적으로 본문으로 설명하는 것이 더 명확합니다.
  • Image Gen을 긴 글을 위한 조판 도구로 사용하는 것.
  • README를 완전한 제품 매뉴얼로 작성하는 것. 자세한 문서는 docs/에 넣어야 합니다.

전체 흐름

Phase 0    프로젝트 읽기 및 패턴 인식
Phase 1    프로젝트 스토리 추출
Phase 2    시각적 생성 방식 선택
Phase 3    작품 수준의 시각적 자산 생성
Phase 4    README 조립
Phase 5    GitHub 메타 정보 제안
Phase 6    검증 및 전달

Phase 0: 프로젝트 읽기 및 패턴 인식

템플릿을 바로 쓰지 않고 먼저 프로젝트를 읽습니다.

확인:

ls
find . -maxdepth 2 -type f | sed 's#^\./##' | sort | head -80

우선 읽을 것:

  • README.md
  • package.json / pyproject.toml / go.mod / Cargo.toml
  • docs/
  • 주요 진입 파일
  • 예제, 스크린샷, 데모 파일

시나리오와 시각적 예산 판단:

시나리오판단 방식전략이미지 제한
새 READMEREADME가 없거나 매우 짧음완전히 생성하지만 경로를 짧게 유지1-2
README 업그레이드기존 README에 유효한 내용이 있음고유한 내용은 유지하고 구조와 첫 화면 재작성0-2
포트폴리오 강화사용자가 미학, 스토리, 전시를 강조내러티브와 커버 표현 우선2
순수 문서 모드SDK, 라이브러리, 백엔드 도구, 인프라그림 적게, 설치, API, 문서 입구 중점0-1
UI / 제품 전시인터페이스, 스크린샷, 데모, 시각적 결과 있음실제 결과 또는 커버로 이해 보조1-2

기존 README를 업그레이드할 때 사용자의 중요한 내용을 삭제하지 마십시오. 먼저 유지할 내용을 추출한 다음 재구성합니다.

노이즈 제거 검토

README를 작성하기 전에 어떤 내용을 외부로 이동하거나 삭제할지 표시합니다:

내용기본 처리
디자인 평가표, 작업 원칙, 내부 방법론SKILL.md 또는 docs/에 보관, README에 넣지 않음
생성된 파일 트리, 템플릿 변수, 스크립트 세부 정보사용자가 개발 문서를 필요로 할 때만 유지
세 번째 흐름도삭제하고 2-4줄 본문 또는 짧은 목록으로 대체
과도한 소셜 링크GitHub / 홈페이지 등 핵심 진입로만 유지
너무 광범위한 기능 목록3개의 결과 중심 능력으로 통합
설치 전의 긴 배경 설명단축하고 빠른 시작을 앞으로 이동

Phase 1: 프로젝트 스토리 추출

7가지 필드를 수집하거나 추론합니다:

필드설명
project_name프로젝트 공식 이름
tagline한 줄 가치 제안, 짧고 명확함
origin프로젝트가 등장한 배경: 왜 필요한가
audience누가 사용할 것인가
promise사용자에게 어떤 결과를 제공하는가
proof실제 능력, 스크린샷, 출력, 예제, 지표
start가장 짧은 시작 경로

너무 많은 질문을 하지 마십시오. 프로젝트에서 추론할 수 있으면 바로 추론합니다. 내러티브의 정확성에 영향을 미칠 때만 사용자에게 질문합니다.

권장 내러티브 구조

프로젝트 이름
한 줄 가치 제안
시각적 커버 (프로젝트 유형에 따라 결정)

이것은 무엇인가
왜 필요한가
무엇을 얻을 수 있는가
빠른 시작
예제 또는 출력
작동 방식 (본문, 기본적으로 이미지 없음)
설치
라이선스
작성자

프로젝트가 도구, 라이브러리 또는 인프라에 가까우면 "빠른 시작"을 "왜 필요한가" 뒤로 이동합니다. README의 순서는 템플릿의 완전성이 아니라 독자의 행동을 돕는 데 있어야 합니다.


Phase 2: 시각적 생성 방식 선택

README 이미지에는 두 가지 유형이 있습니다:

  1. 작품 커버: 분위기, 주제, 기억 포인트를 전달합니다.
  2. 구조 설명도: 단계, 능력, 비교, 흐름을 전달합니다.

사용자 의도에 따라 모드를 선택합니다:

모드적용 시나리오이미지 전략
portfolio기본 권장, 완전한 작품 감각이 필요한 프로젝트에 적합1장 커버 + 1장 핵심 능력 이미지
clean-docSDK, 라이브러리, 백엔드 도구, 엄격한 인프라0-1장, 빠른 시작 및 예제 우선
visual-storyAI 도구, 디자인 도구, 독립 제품, 작품 전시최대 2장, Codex Image Gen이 기억 포인트 담당
structured사용자가 명시적으로 정보 그래픽, 비교, 흐름도를 요구1-2장 HTML/CSS 포스터, 텍스트 정확성 보장

기본적으로 프로젝트 유형을 먼저 판단하고, portfolio를 강제로 적용하지 마십시오. 시각적 자산 생성 우선 순위는 고정되어 있습니다:

  1. Codex Image Gen Skill: Codex 내장 이미지 생성 기능을 우선 사용하여 시각적 자산을 생성합니다.
  2. 경량화: README 표시 이미지는 우선 WebP로 변환한 다음 README 참조 경로에 씁니다.
  3. HTML to PNG fallback: Image Gen을 사용할 수 없거나, 출력이 요구 사항을 충족하지 못하거나, 사용자가 명시적으로 구조화된 정확한 텍스트를 요구하는 경우에만 HTML/CSS 템플릿 스크린샷으로 대체합니다.

HTML 스크린샷을 기본 경로로 사용하지 마십시오. 신뢰할 수 있는 대체 수단이지 기본 시각적 솔루션이 아닙니다.


Phase 3: 작품 수준의 시각적 자산 생성

기본 출력은 두 개의 안정적인 파일 이름을 사용합니다:

assets/banner.webp
assets/features.webp

이렇게 하면 이미지가 Codex Image Gen에서 왔든 HTML 스크린샷 대체에서 왔든 README 참조 경로가 안정적입니다.

이미지 역할

이미지목표권장 방식
banner.webp프로젝트 명함, 프로젝트 이름, 포지셔닝 및 기억 포인트 구축Codex Image Gen 우선
features.webp핵심 능력, 결과 또는 필요한 흐름의 전파 이미지Codex Image Gen 우선; 텍스트 정확성이 필요하면 HTML 대체

workflow.png 또는 workflow.webp를 기본으로 생성하지 마십시오. 사용자가 명시적으로 흐름도를 요구하면 흐름 내용을 features.webp에 통합하거나 본문에 넣고 세 번째 이미지를 추가하지 마십시오.

기본 시각적 스타일

모든 README 시각적 자산은 기본적으로 동일한 스타일을 채택합니다:

검은 배경, 미니멀리스트, 영화 조명, 높은 대비, 큰 여백, 낮은 밝기, 흰색/회색/따뜻한 골드 세 가지 색상, 프리미엄 매거진 커버 느낌.
화면 질감: #050505 진한 검은색 배경, 종이 입자, 얕은 심도, 체적 안개, 얇은 윤곽 조명, 국부 금속 질감.
품질 목표: 1만 별 디자이너 수준의 작품.

디자인 제약:

  • 배경은 주로 #050505 진한 검은색을 사용합니다.
  • 색상은 흰색, 회색, 따뜻한 골드만 사용합니다. 무지개 그라데이션, 보라색-파란색 네온 또는 고채도 장식 색상을 도입하지 마십시오.
  • 큰 여백과 국부 조명을 사용하고 요소를 쌓지 마십시오.
  • 이미지는 소량의 고가치 텍스트를 포함해야 하며, 전파 및 포지셔닝 역할을 하고 긴 설명을 하지 않습니다.
  • 텍스트가 적을수록 강력합니다: 각 이미지는 독자가 README를 떠난 후에도 기억해야 할 정보만 유지합니다.
  • 단락, 명령, 표, 버전 번호 스택 및 밀집 설명을 넣지 마십시오.

프로젝트 명함 텍스트 전략

기본적으로 순수한 분위기 이미지가 아닌 '프로젝트 명함형 이미지'를 사용합니다.

이미지권장 텍스트제한
banner.webp프로젝트 이름 + 한 줄 포지셔닝 + 1-3개의 짧은 태그영어 18단어 또는 한자 28자
features.webp2-3개의 결과 구문, 필요한 경우 짧은 제목 추가각 구문 2-5단어

좋은 텍스트는 설명서 제목처럼 보여야 하며, 설명서처럼 보이지 않아야 합니다:

  • 프로젝트 이름은 명확해야 하며, 우선 banner.webp에 배치합니다.
  • 포지셔닝 문장은 결과를 말하고 구호를 말하지 않습니다. 예: "Portfolio-grade README design for open source projects".
  • 태그는 검색 및 기억 가치가 가장 높은 단어만 넣습니다. 예: Story, Visual, Signal.
  • 한국어를 사용할 수 있지만 적게 사용합니다. 영어 프로젝트 이름, 짧은 영어 태그가 일반적으로 더 안정적입니다.
  • Image Gen이 텍스트를 잘못 쓰면 한 번 재시도합니다. 여전히 정확하지 않으면 Image Gen 시각적 배경을 유지하고 HTML/CSS fallback으로 정확한 텍스트를 담습니다.
  • "전체 AI 생성"을 위해 프로젝트 이름과 포지셔닝의 정확성을 희생하지 마십시오.

글자 크기 기준

1920×1080으로 디자인할 때:

요소최소 글자 크기
주 제목92px
한자 주 제목80px
큰 카드 제목48px
본문 설명28px
보조 태그22px
바닥글20px

18px 이하의 텍스트를 사용하지 마십시오. GitHub에서 축소되면 읽을 수 없습니다.

Codex Image Gen 산출물은 16:9와 충분한 선명도만 유지하면 됩니다. 좋은 이미지를 1920×1080에 맞추기 위해 강제로 리샘플링하지 마십시오. README 표시 이미지는 WebP로 저장하는 것이 우선입니다. 1920×1080은 HTML to PNG fallback의 템플릿 크기입니다.

HTML to PNG fallback

Image Gen을 사용할 수 없거나, 사용자가 정확한 구조화된 텍스트를 요구하거나, Image Gen 출력이 검사를 통과하지 못하는 경우에만 사용합니다:

node scripts/gen_infographic.mjs /tmp/readme-banner.html assets/banner.png 1920 1080
node scripts/gen_infographic.mjs /tmp/readme-features.html assets/features.png 1920 1080
node scripts/convert_webp_assets.mjs assets/banner.png assets/banner.webp assets/features.png assets/features.webp

템플릿 출처:

templates/banner.html
templates/features.html

템플릿 변수:

{{PROJECT_NAME}}
{{TAGLINE}}
{{PRIMARY_COLOR}}
{{CATEGORY}}
{{PLATFORM}}
{{LANGUAGE}}
{{VERSION_INFO}}
{{TECH_CARDS}}
{{FEATURE_CARDS}}
{{FEATURE_COUNT}}

카드 구조:

  • {{TECH_CARDS}}는 커버 오른쪽에 사용하며, 2-3개를 권장하고, 짧은 태그와 한 줄 설명만 넣습니다.
  • {{FEATURE_CARDS}}는 2-3개의 큰 카드만 넣고, 첫 번째 카드에 featured를 추가할 수 있습니다.
  • 작업 흐름을 표현해야 하는 경우 features.webp의 3가지 결과 단계로 처리하고, 새 이미지를 추가하지 않습니다.

Codex Image Gen / gpt-image-2 방식

기본적으로 Codex 내장 이미지 생성 기능을 우선 호출하고, 프로젝트에 임시로 API 스크립트를 하드코딩하지 마십시오.

Image Gen에 적합한 내용:

  • README 커버.
  • 제품 분위기 이미지.
  • 포트폴리오 시각 자료.
  • 추상 개념 이미지.
  • 기존 이미지를 사용한 스타일 확장.

Image Gen에 부적합한 내용:

  • 정확한 흐름도.
  • 많은 한국어 텍스트 또는 여러 단락 설명.
  • 명령, 버전, 표.
  • 단어 단위로 정확해야 하는 긴 텍스트 또는 UI 이미지.

권장 prompt 구조:

Use case: productivity-visual
Asset type: GitHub README visual asset, 16:9
Project: <project_name>
Story: <origin + promise>
Visual direction: black background, minimalist, cinematic lighting, high contrast, large negative space, low brightness, premium magazine cover
Texture and lighting: #050505 deep black background, subtle paper grain, shallow depth of field, volumetric haze, thin rim light, selective metallic highlights
Palette: white, gray, warm gold only
Composition: one strong visual idea, restrained, spacious, no dense UI
Quality bar: 10k-star designer portfolio quality
Text policy: include only high-value name-card text. Use the exact project name, one short positioning line, and optional 1-3 short labels. No paragraphs, commands, tables, tiny captions, or decorative text.
Avoid: emoji, clutter, fake interface text, tiny labels, generic gradients, bright neon, overdesigned dashboards

Image Gen이 지원되지 않거나, 호출할 수 없거나, 출력에 오류 텍스트/스타일 편차가 있는 경우 먼저 더 짧은 텍스트 prompt로 한 번 재시도합니다. 여전히 정확하지 않으면 HTML to PNG fallback 프로세스로 돌아가 정확한 텍스트를 담습니다.

이미지 경량화

README 표시 이미지는 기본적으로 WebP를 사용합니다. WebP는 일반적으로 README 로딩에 PNG보다 적합합니다. PNG는 HTML 스크린샷 fallback의 중간 산출물, 투명 이미지 또는 무손실 저장이 필요할 때만 사용합니다.

기본 명령:

npm run webp

프로젝트에 WebP 변환 스크립트가 없으면 cwebp, sips 또는 사용 가능한 경량 도구를 우선 사용합니다. 변환을 위해 무거운 종속성을 도입하지 마십시오. 변환할 수 없으면 PNG를 유지하고 이유를 설명합니다.

시각적 검사

각 이미지 생성 후 확인:

  • GitHub README 표시 너비로 축소해도 읽을 수 있는가.
  • 하나의 이미지가 하나의 핵심만 말하고 있는가.
  • 작은 글씨가 쌓여 있지 않은가.
  • 프로젝트 이름과 포지셔닝 문장이 한눈에 보이는가.
  • 이미지 내 텍스트에 철자 오류, 깨짐 또는 가짜 텍스트가 없는가.
  • 과도한 장식이 없는가.
  • 시각적 스타일이 프로젝트 스토리와 일치하는가.
  • Image Gen 이미지에 오류 텍스트나 불필요한 워터마크가 없는가.
  • 압축 후 이미지가 여전히 선명하고, 눈에 띄는 색 밴드, 노이즈 손상 또는 텍스트 흐림이 없는가.

Phase 4: README 조립

기본 구조:

<div align="center">

# 프로젝트 이름

**한 줄 가치 제안**

<img src="assets/banner.webp" alt="[프로젝트 이름] — [가치 제안]" width="100%">

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

</div>

---

## 이것은 무엇인가

[2-3문장으로 프로젝트, 배경, 결과 설명.]

## 왜 필요한가

[실제 문제를 설명하고, 안티패턴 목록을 나열하지 않음.]

## 무엇을 얻을 수 있는가

<img src="assets/features.webp" alt="[3가지 핵심 능력]" width="100%">

## 작동 방식

[2-4줄로 작동 방식 설명; 기본적으로 세 번째 이미지를 넣지 않음.]

## 빠른 시작

[가장 짧은 실행 가능 경로.]

## 설치

[의존성 및 설치 명령.]

## 라이선스

[MIT](./LICENSE)

## 작성자 정보

[간결한 작성자 정보.]

규칙:

  • 프로젝트에 상태 표시가 실제로 필요하지 않으면 3개 이상의 배지를 사용하지 마십시오.
  • 이미지 뒤에 동일한 기능 목록을 반복하지 마십시오.
  • "디자인 원칙", "프로젝트 구조", "생성 내용"을 모두 README에 채워 넣지 마십시오. 독자에게 유용한 부분만 유지합니다.
  • 기본적으로 세 번째 workflow 이미지를 넣지 마십시오. 두 장의 이미지로 작품 감각과 핵심 정보를 충분히 전달할 수 있습니다.
  • 자세한 설명은 docs/에 넣고, README는 입구 역할만 합니다.

Phase 5: GitHub 메타 정보 추천

Repository Description과 Topics는 GitHub 검색, Trending 연관, AI 검색 참조 및 빠른 수동 판단의 입구입니다. README 내용이 아니므로 README.md에 쓰지 마십시오. 최종 응답에서 독립적인 제안으로만 출력합니다.

제일 원리 목표

  • Description 질문에 답: 이 프로젝트는 누구를 위해 어떤 결과를 창출하는가.
  • Topics 질문에 답: 이 프로젝트는 어떤 검색 버킷에 포함되어야 하는가.
  • 추천 개수는 신호 품질에 의해 결정되며, 개수를 쫓지 않습니다. 고품질 7-9개가 일반적으로 20개를 채우는 것보다 낫습니다.
  • Trending / SEO / GEO 세 가지 균형: 인기 검색어를 커버하면서도 프로젝트 사실의 정확성을 유지하여 AI 참조를 용이하게 합니다.

Description 생성 규칙

3개의 후보를 생성하고 각각 점수를 매깁니다:

[동사] [특정 결과] for [대상] — [1-3개의 정확한 키워드]

하드 제약:

  • 영어 우선, ≤ 160자.
  • 동사로 시작: Design / Generate / Build / Create / Convert / Automate.
  • 프로젝트의 가장 핵심적인 2-3개의 키워드를 포함.
  • 이모지, 느낌표, 마케팅 형용사 사용 금지.
  • 프로젝트 사실로 입증할 수 없는 능력을 쓰지 않음.

평가:

차원점수판단
정확성40프로젝트의 실제 능력에 충실한가
검색 가치25GitHub / Google에서 자주 검색되는 단어를 커버하는가
AI 참조 가능성20ChatGPT / Claude / Perplexity가 직접 이해할 수 있는가
절제 정도15과장이나 군더더기가 없는가

별점:

점수별점
90-1005성, 사용 권장
80-894성, 사용 가능하지만 더 간결하게 다듬을 수 있음
70-793성, 대안으로만 적합
< 70권장하지 않음

Topics 생성 규칙

먼저 후보 풀을 구축한 다음 최종 추천을 선별합니다.

후보 출처:

  • 프로젝트 유형: agent-skill, cli-tool, developer-tools, documentation
  • 핵심 기술: nodejs, playwright, codex, image-generation
  • 응용 분야: readme, github-readme, open-source, portfolio
  • 현재 트렌드: AI agent, image generation, developer tooling, documentation automation
  • 프로젝트 실제 파일 및 README 내러티브에 나타나는 키워드

선별 규칙:

  • 7-9개를 추천하고, 10개를 초과하지 않습니다. 프로젝트가 실제로 여러 명확한 영역에 걸쳐 있지 않으면 더 늘리지 않습니다.
  • Topic은 소문자여야 하며, 문자, 숫자 및 하이픈만 사용합니다.
  • 너무 광범위한 단어는 삭제: software, tool, app, github, project, ai.
  • 중복 단어 삭제: readme와 github-readme는 공존할 수 있습니다. open-source와 opensource는 하나만 유지합니다.
  • 인기를 쫓기 위해 실제와 다른 topic을 추가하지 않습니다.

각 topic에 별점과 이유를 제공합니다:

별점의미
5성강력한 연관성, 높은 검색 가치, 추가해야 함
4성연관성이 있고 발견 가치가 있음, 추가 가능
3성어느 정도 관련이 있지만 충분히 핵심적이지 않음
2성연관성이 약함, 일반적으로 권장하지 않음
1성노이즈, 추가하지 않음

출력 형식:

GitHub Description 추천:

1. ★★★★★ <description>
   이유: ...

2. ★★★★☆ <description>
   이유: ...

최종 추천: <description>

GitHub Topics 추천:

추가:
- ★★★★★ github-readme — 프로젝트 용도를 정확하게 설명
- ★★★★★ agent-skill — 프로젝트 형태에 부합
- ★★★★☆ image-generation — 프로젝트가 Image Gen을 지원할 때 추가

추가하지 않음:
- ★★☆☆☆ ai — 너무 광범위하여 검색 노이즈가 큼
- ★★☆☆☆ github — 너무 광범위하여 분류에 도움이 되지 않음

선택적 gh CLI 업데이트

사용자가 gh를 설치했고, 현재 디렉토리가 Git 리포지토리이며, GitHub remote를 확인할 수 있으면 Agent가 gh repo edit을 사용하여 업데이트할 것을 제안할 수 있습니다. 함부로 업데이트하지 마십시오. 먼저 실행할 내용을 제공하고 사용자 확인을 기다려야 합니다.

확인:

gh --version
git remote -v

권장 명령 형식:

gh repo edit OWNER/REPO \
  --description "<final-description>" \
  --add-topic topic-one \
  --add-topic topic-two \
  --add-topic topic-three

이전 topics를 교체해야 하는 경우 먼저 현재 topics를 읽은 다음 명확히 권장되지 않는 항목만 제거합니다:

gh repo view OWNER/REPO --json description,repositoryTopics
gh repo edit OWNER/REPO --remove-topic old-topic --add-topic new-topic

설명: git은 리포지토리 메타 정보를 업데이트할 수 없습니다

git 명령은 GitHub 리포지토리의 Description 또는 Topics를 수정할 수 없습니다. 이유: Description과 Topics는 GitHub 플랫폼 메타 정보이며, Git 리포지토리의 커밋, 브랜치, 태그 또는 remote 구성이 아닙니다.

git remote -v는 OWNER/REPO를 식별하는 데만 사용할 수 있으며, 메타 정보를 업데이트하는 데 사용할 수 없습니다.

gh가 없으면 추천 값만 제공하고 사용자가 GitHub 페이지에서 수동으로 업데이트하도록 합니다. 복잡한 대체 명령을 제공하지 마십시오.

README 파일에 이러한 추천을 저장하지 마십시오. 이는 전달 시 사용자에 대한 작업 제안에 속합니다.


Phase 6: 검증 및 전달

전달 전 반드시 검증:

node --version
npm run showcase
file assets/banner.webp assets/features.webp
git status --short

템플릿이나 실제 이미지를 변경한 경우 반드시 WebP를 다시 생성하고 열어서 확인합니다.

최종 보고서는 다음만 명확히 밝힙니다:

  • 무엇을 변경했는가.
  • 결과는 어떠한가.
  • 어떤 검증을 통과했는가.
  • 사용자가 결정해야 할 사항이 남아 있는가.

구현 세부 사항과 장황한 과정을 사용자에게 쓰지 마십시오.

관련 스킬