Community이미지github.com

share-cards

모든 웹페이지에 맞춤형 Open Graph 미리보기 이미지(1200x630)를 생성하고, 빌드 시 각 페이지의 제목, 설명, 표준 주소, 메타 태그를 HTML에 주입합니다. 채팅 앱이나 소셜 사이트에서 링크를 공유할 때 올바른 미리보기가 표시되도록 합니다.

share-cards란 무엇인가요?

이 스킬은 SPA(Single-Page Application)를 포함한 모든 웹사이트에서 페이지별 Open Graph 이미지와 메타 태그를 자동 생성해주는 도구입니다. 미리보기 크롤러(채팅 앱, 소셜 사이트, 검색 엔진)는 JavaScript를 실행하지 않기 때문에, SPA는 모든 URL에 동일한 HTML을 제공하여 잘못된 미리보기를 보여줍니다. share-cards는 두 가지 핵심 기능으로 이 문제를 해결합니다: (1) 하나의 HTML 템플릿과 페이지 목록으로 헤드리스 브라우저에서 페이지별 1200x630 JPEG 이미지를 렌더링하고, (2) 빌드된 index.html을 각 페이지별 HTML 파일로 분할하여 각각 고유한 <title>, description, canonical URL, og:* 및 twitter:* 태그를 주입합니다. Claude Code, Cursor 등 AI 코딩 에이전트에서 사용 가능하며, Vite 플러그인을 지원하고 config 파일(cards.config.json) 기반으로 동작합니다. 프로젝트의 정적 폴더 내에 이미지를 생성하고, 빌드 시점에 메타 태그를 주입하여 배포 후 채팅 앱에서 링크를 붙여넣었을 때 정확한 미리보기가 표시되도록 보장합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VinVirtual/share-cards/tree/HEAD

Installed? Explore more 이미지 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

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

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

문서

share-cards은(는) 무엇을 하나요?

미리보기 크롤러(채팅 앱, 소셜 사이트, 검색 엔진)는 서버가 보내는 HTML을 읽고 JavaScript를 실행하지 않습니다. 단일 페이지 앱(SPA)은 모든 주소에 동일한 HTML을 보내므로, 모든 링크가 같은 미리보기를 표시합니다. share-cards는 이 두 가지 문제를 해결합니다:

  1. 렌더링: 하나의 HTML 템플릿 + 페이지 목록 → 페이지별 1200x630 JPEG 이미지, 헤드리스 브라우저에서 생성.
  2. 주입: 빌드된 index.html → 페이지별 HTML 파일, 각각 고유한 <title>, description, canonical, og:*, twitter:* 태그 포함.

스킬 폴더: ~/.claude/skills/share-cards/ (이하 $S). 모든 명령어는 $S/cards <command> [dir] 형태이며, [dir]에 cards.config.json이 있어야 합니다. $S/cards help 명령어로 목록을 확인할 수 있습니다.

$S/cards                    명령줄 도구
$S/lib/                     설정, 태그 주입, 렌더링, 검증, 미리보기, 재작성 규칙
$S/templates/               editorial.html, minimal.html, technical.html, runtime.js
$S/vite-plugin.mjs          `vite build` 이후 inject 실행
$S/references/templates.md  슬롯, 변수 및 나만의 템플릿 작성 방법
$S/examples/site/           4페이지로 구성된 예제 사이트 (카드 및 주입된 페이지 포함)
$S/README.md                설정 참조, 프레임워크 참고 사항, 제한 사항

워크플로우

  1. 머신 확인: $S/cards check. render와 preview 명령어만 브라우저가 필요합니다.
  2. 페이지 찾기: 프로젝트의 라우터 또는 콘텐츠 폴더를 읽고 모든 공개 주소를 나열하세요. 정적 파일이 제공되는 위치(public/, static/)와 빌드 결과물이 생성되는 위치(dist/, build/, out/)를 찾으세요.
  3. 스캐폴딩: $S/cards init <project> (페이지 목록을 프로젝트 자체의 라우트나 콘텐츠 데이터에서 가져와야 해서 불일치가 발생하지 않도록 하려면 --mjs 플래그를 추가하세요). siteUrl (실제 https:// 도메인), siteName, imageDir (정적 폴더 내 경로, 예: public/og), imageUrlPath (해당 폴더가 제공되는 URL 경로, 예: /og), dist를 설정하세요.
  4. 각 페이지의 항목 작성:
    • title: 미리보기에 표시될 전체 페이지 제목.
    • description: 한 문장, 최대 160자.
    • cardTitle: 카드에 그려질 단어. 짧게 유지(약 2~6단어). *별표*는 강조 색상으로 그려질 단어를 표시합니다.
    • cardDescription (선택 사항, 카드용 짧은 줄), kicker (작은 레이블), art (프로젝트의 이미지 파일), template (페이지별 재정의).
    • 이러한 항목에 대해 사실, 숫자, 인용문을 절대 지어내지 마세요. 페이지 자체의 단어를 사용하세요.
  5. 템플릿 및 테마 선택: editorial (종이 질감, 두꺼운 세리프), minimal (흰색, 조용함), technical (어두운 배경, 고정폭 글꼴). theme을 프로젝트 자체 색상으로 설정하세요. 다른 템플릿이 필요하면 $S/cards eject <name> card.html을 실행하고 편집한 후 "template": "./card.html"로 설정하세요. 자세한 내용은 references/templates.md를 참조하세요.
  6. 렌더링: $S/cards render <project>. 모든 경고를 읽으세요: 제목이나 설명이 잘리면 텍스트를 짧게 해야 합니다.
  7. 결과 확인: $S/cards preview <project> 명령어는 cards-preview/contact-sheet.png와 chat-preview.png 파일을 생성합니다. 두 PNG 파일을 모두 읽으세요. 각 카드에서 잘린 단어, 혼잡함, 대비 부족, 텍스트를 가리는 아트워크가 있는지 확인하세요. 수정 후 다시 렌더링하세요. 직접 확인하지 않고 사용자에게 카드가 올바르다고 말하지 마세요.
  8. 페이지 셸 준비: inject는 이미 존재하는 태그를 채우며, 태그가 없으면 실패합니다. $S/cards tags <project>를 실행하고 출력 블록을 소스 index.html의 <head>에 붙여넣어 기존 공유 태그를 대체하세요 (또는 --add-missing 플래그 사용).
  9. 빌드에 연결:
    • Vite: $S/vite-plugin.mjs의 shareCards()를 plugins 배열에 추가하세요 (README 참조).
    • 그 외: 빌드 명령어 후 $S/cards inject <project>를 실행하세요.
  10. 호스트 규칙: 호스트에 /index.html로의 catch-all 재작성 규칙이 있는 경우, $S/cards rewrites vercel|netlify|netlify-toml <project> 명령어로 페이지 규칙을 출력하고 catch-all 앞에 배치하세요. 사용자에게 규칙을 보여주고, 동의 없이 호스트 설정을 편집하지 마세요.
  11. 검증: 사이트를 빌드한 후 $S/cards verify <project>를 실행하세요. All good. 메시지로 끝나야 합니다.
  12. 남은 작업을 사용자에게 알리기: 배포 후, 채팅 앱에 실제 링크 하나를 붙여넣으세요. 미리보기는 각 앱에 의해 캐시되며, 때로는 며칠 동안 지속됩니다. 카드가 변경될 때마다 이미지 주소를 변경하려면 "versionImages": true를 설정하세요.

규칙

  • siteUrl은 프로덕션 도메인이어야 합니다. 미리보기 이미지는 절대 https:// 주소가 필요합니다.
  • 빌드 전에 카드를 렌더링하여 빌드가 카드를 복사하도록 하고, 카드와 cards.lock.json을 커밋하세요. 그러면 CI에는 브라우저가 필요하지 않습니다.
  • 설정에 "allowNetwork": true가 설정되지 않은 경우 렌더링 중에 네트워크에서 아무것도 가져오지 않습니다. 웹 폰트는 fonts 아래에 나열된 로컬 파일이어야 합니다.
  • 폰트는 기본적으로 시스템 스택을 사용하므로, 다른 머신에서 그린 카드는 다를 수 있습니다. 모든 곳에서 동일한 출력을 원하면 폰트 파일을 프로젝트에 추가하고(라이선스 확인) fonts 아래에 나열하세요.
  • 확인되지 않은 사항을 명확히 말하세요: 각 앱의 실제 크롤러, 배포 후 호스트의 라우팅.

관련 스킬