guizang-social-card-skill: Claude Code로 SNS 카드 일괄 생성하기

5000자짜리 기술 글을 Xiaohongshu 9장 카드로 나눌 때 가장 오래 걸리는 일은 내용 요약이 아닙니다. 각 카드의 레이아웃입니다. 제목을 어느 줄에 둘지, 어떤 색상 버전을 쓸지, 커버 스타일을 통일할지 같은 반복 작업이 제작 시간의 상당 부분을 차지합니다. guizang-social-card-skill은 이 과정을 Claude Code 안으로 가져옵니다. Agent에게 어떤 콘텐츠를 만들지 알려 주면 단일 HTML을 출력하고, Playwright로 로컬 렌더링해 PNG를 만듭니다. 아래에서는 지원하는 아트보드 크기, 두 가지 비주얼 시스템의 차이, 설치와 실행 방법, 렌더링 스크립트 사용법, 검증 규칙, AGPL-3.0 라이선스의 경계를 정리합니다.

프로젝트 포지션: 나에게 맞는 도구인가요?

guizang-social-card-skill은 AI 이미지 생성 프롬프트가 아니라 로컬 렌더링 파이프라인입니다. 핵심 기능은 Claude Code나 Codex 같은 Agent 환경에서 Xiaohongshu 카드와 WeChat 공식 계정 커버를 일괄 생성하는 것입니다. 출력은 단일 HTML이고, Playwright로 PNG를 렌더링합니다. 레이아웃 뼈대와 테마 프리셋은 이미 정해져 있으며, Agent는 콘텐츠를 채우고 파라미터를 조정하는 역할을 합니다.

다음 표를 보면 사용할지 빠르게 판단할 수 있습니다.

스타일이 통일된 커버 이미지를 빠르게 만들고 싶고 AGPL-3.0의 오픈소스 의무를 받아들일 수 있다면, 수동 레이아웃 시간을 크게 줄일 수 있습니다. 반대로 더 세밀한 브랜드 제어, 비공개 상업적 이용, 복잡한 승인 프로세스가 필요하다면 이 도구의 제약이 맞지 않을 수 있습니다.

두 가지 비주얼 시스템과 세 가지 아트보드

Editorial vs Swiss: 스타일 차이

프로젝트에는 서로 다른 콘텐츠 유형을 위한 두 가지 비주얼 시스템이 들어 있습니다.

Editorial은 잡지형 레이아웃에 가깝고 텍스트 중심 카드에 잘 맞습니다. Swiss는 데이터 차트에 더 가까워 비교형 콘텐츠나 구조를 강조해야 하는 정보에 적합합니다. 두 시스템을 합치면 28개의 레이아웃 뼈대와 10세트의 테마 프리셋이 있어, 대부분의 Xiaohongshu 카드와 WeChat 공식 계정 커버 스타일을 커버할 수 있습니다.

세 가지 아트보드 크기

아트보드 크기는 출력 이미지의 비율을 결정합니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

WeChat 공식 계정은 보통 와이드 버전과 정사각형 버전 커버를 함께 준비해야 합니다. Xiaohongshu 카드는 1080×1440으로 통일합니다. 이 크기는 README의 아트보드 정의에서 나온 것이며 Xiaohongshu나 WeChat의 공식 심사 규칙을 뜻하지 않습니다. 게시 전에는 각 플랫폼의 현재 요구사항을 다시 확인해야 합니다.

설치: CLI와 Clone 두 가지 방식

방법 1: CLI 설치(권장)

전제 조건은 Claude Code 또는 Codex가 이미 설치되어 있고 Agent를 정상적으로 호출할 수 있어야 한다는 점입니다. 터미널에서 다음 명령을 실행합니다.

npx skills add https://github.com/op7418/guizang-social-card-skill --skill guizang-social-card-skill

이 명령은 Skill을 Claude Code의 개인 디렉터리에 설치합니다. 설치가 끝나면 Claude Code에서 /guizang-social-card-skill을 직접 호출하거나, 관련 작업에서 Agent가 자동으로 발견해 사용하게 할 수 있습니다.

Skill의 기본 개념이 아직 익숙하지 않다면 먼저 이 입문 글을 참고해도 좋습니다: 프롬프트를 매번 손으로 쓰느라 지쳤다면, Claude Code의 이 기능으로 효율을 3배 높이기.

방법 2: 로컬에 Clone하기

템플릿이나 레이아웃을 수정해야 한다면 프로젝트를 직접 clone할 수 있습니다.

git clone https://github.com/op7418/guizang-social-card-skill ~/.claude/skills/guizang-social-card-skill

clone 후 디렉터리 구조는 대략 다음과 같습니다.

guizang-social-card-skill/
├── SKILL.md
├── templates/
├── scripts/
│   ├── render.mjs
│   └── validate-social-deck.mjs
└── references/

로컬 커스터마이즈의 장점은 템플릿, 글자 크기, 색상을 직접 바꿀 수 있다는 점입니다. 하지만 수정한 버전도 AGPL-3.0의 제약을 받습니다. 재배포하거나 네트워크 서비스로 제공할 때는 소스를 공개해야 합니다.

렌더링과 검증: HTML에서 PNG로

렌더링 스크립트 사용법

Agent가 단일 HTML을 출력한 뒤에는 Playwright로 PNG를 렌더링해야 합니다. 프로젝트는 렌더링 스크립트를 제공합니다.

node render.mjs

이 스크립트는 현재 작업 디렉터리의 HTML 파일을 읽고 Playwright 헤드리스 브라우저로 렌더링한 뒤, 같은 디렉터리에 PNG를 출력합니다. 렌더링 과정에서 자주 만나는 문제는 다음과 같습니다.

• Playwright 미설치: 먼저 npx playwright install chromium을 실행합니다.
• HTML 파일 경로 오류: Agent가 출력한 파일명이 스크립트의 기대와 맞는지 확인합니다.
• 폰트 부족: 중국어 또는 한국어 폰트가 로컬에 없으면 빈 영역으로 렌더링될 수 있습니다.

렌더링이 끝나면 이미지 결과를 한 번 직접 확인하는 것이 좋습니다. 특히 긴 제목, 마스크로 인한 가림, 인물 얼굴 회피, footer 충돌 같은 문제는 스크립트만으로 완전히 잡기 어렵습니다.

🔥 수요 없는 제품에 3개월을 낭비하지 마세요! 소액의 예산으로 Adsterra에서 SaaS 메시지를 빠르게 검증하기 →

지금 테스트 →광고

검증 스크립트 사용법

프로젝트에는 품질 검증 스크립트도 있습니다.

node validate-social-deck.mjs path/to/task-dir

검증 규칙은 다음 6가지입니다.

1. 오버플로 감지: 텍스트가 아트보드 경계를 넘으면 표시합니다.
2. 글자 크기 상한: 제목 글자 크기가 임계값을 넘으면 오류를 냅니다.
3. footer 충돌: 하단 footer와 본문 콘텐츠가 겹치면 표시합니다.
4. 가로 밴드 밀도: Swiss 시스템의 가로 밴드가 지나치게 빽빽하면 경고합니다.
5. frame 오버플로: 레이아웃 뼈대의 frame 경계가 아트보드 밖으로 나가면 표시합니다.
6. Swiss 글자 두께: Swiss 시스템의 font-weight 설정이 규칙에 맞지 않으면 오류를 냅니다.

검증 스크립트는 레이아웃 문제를 빠르게 찾는 데 도움을 주지만 자동으로 고치지는 않습니다. HTML 템플릿이나 Agent 출력으로 돌아가 파라미터를 조정한 뒤 다시 렌더링해야 합니다.

Agent가 규칙에 더 맞는 HTML을 출력하게 만들고 싶다면 이 설정 가이드도 참고할 수 있습니다: Claude가 코드를 제멋대로 쓰지 않게 하는 설정 파일로 AI 정확도를 10% 높이기.

소재 출처와 라이선스 리스크

이미지 소스 워크플로

프로젝트는 여러 이미지 소스에서 소재를 가져올 수 있습니다.

• Unsplash: 무료 고품질 이미지. 대부분 상업적 사용 가능
• Pexels: 무료 이미지. 구체적인 라이선스 조항 확인 필요
• Flickr CC: Creative Commons 이미지. 출처와 라이선스 유형 표기 필요
• Wallhaven: 배경화면 계열 이미지. 상업적 사용 전 라이선스 확인 필요
• 검색 결과: 일반 검색 엔진에서 가져온 이미지. 라이선스 상태가 불확실함

Agent는 요구사항에 따라 이미지 소스를 선택할 수 있지만, 소재의 라이선스 상태를 자동으로 검증하지는 않습니다. 게시 전에는 각 이미지의 출처와 라이선스 조항을 사람이 확인해야 합니다. 특히 상업적 이용에서는 더 중요합니다. 이미지가 “상업적 사용 불가” 또는 “출처 표기 필요”로 표시되어 있다면 카드 안에 관련 정보를 남겨야 합니다.

AGPL-3.0 라이선스 해석

프로젝트는 AGPL-3.0 라이선스를 사용하며 MIT나 Apache보다 더 엄격합니다. 핵심 요구사항은 다음과 같습니다.

팀에 비공개 소스 요구사항이 있거나 이 도구를 비공개 제품에 통합하려 한다면, 상업적 사용 전에 준수 여부를 확인해야 합니다. AGPL-3.0은 네트워크 서비스로 제공할 때 서버 측 코드 공개를 요구합니다. 일부 상업 팀에는 이 조건이 큰 제약이 될 수 있습니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

리스크 안내

몇 가지 경계를 분명히 해야 합니다.

• 프로젝트는 PNG 자산만 생성하며 대량 게시나 자동 게시 기능을 제공하지 않습니다.
• 아트보드 크기는 README 정의에서 나온 것이며 Xiaohongshu나 WeChat의 공식 심사 규칙이 아닙니다.
• Stars와 Forks 수는 계속 변하므로 핵심 가치의 근거로 삼기 어렵습니다.
• 소재 라이선스는 사람이 확인해야 하며 Agent가 자동으로 끝낼 수 없습니다.

Agent 라이선스와 컴플라이언스가 더 궁금하다면 이 하위 에이전트 가이드도 참고할 수 있습니다: Claude 답변이 너무 길다면 Subagent로 나만의 AI 팀 만들기.

더 읽을 글

Claude Code Skill과 Agent 도구를 더 체계적으로 이해하고 싶다면 다음 글도 도움이 됩니다.

• 프롬프트를 매번 손으로 쓰느라 지쳤다면, Claude Code의 이 기능으로 효율을 3배 높이기: Skill의 기본 개념과 프롬프트 재사용 가치
• Claude가 코드를 제멋대로 쓰지 않게 하는 설정 파일로 AI 정확도를 10% 높이기: CLAUDE.md로 Agent 출력을 규정하는 방법
• Claude 답변이 너무 길다면 Subagent로 나만의 AI 팀 만들기: 하위 에이전트 아키텍처와 여러 Agent 협업

모두 Claude Code 사용 팁을 실전 중심으로 정리한 글입니다. Skill이 Agent 워크플로에서 어떤 위치를 차지하는지 이해하는 데 도움이 됩니다.

결론

guizang-social-card-skill은 Xiaohongshu 카드와 WeChat 공식 계정 커버 제작 흐름을 Claude Code 안으로 가져와, Agent로 스타일이 통일된 카드를 일괄 생성할 수 있게 합니다. 두 가지 비주얼 시스템, 세 가지 아트보드 크기, 28개의 레이아웃 뼈대, 10세트의 테마 프리셋을 내장해 대부분의 콘텐츠 운영 상황을 커버합니다.

하지만 경계도 분명합니다. 생성하는 것은 PNG 자산뿐이며 게시 기능은 제공하지 않습니다. 소재 라이선스는 사람이 확인해야 합니다. AGPL-3.0은 상업적 사용 전에 오픈소스 의무를 확인하라고 요구합니다. 사진 정밀 보정, 복잡한 브랜드 승인, 비공개 상업적 이용이 필요하다면 이 도구의 제약이 맞지 않을 수 있습니다.

다음 단계로는 GitHub 링크를 열고 CLI 명령으로 Skill을 설치한 뒤 첫 카드 세트를 만들어 보는 것이 좋습니다. 렌더링 문제가 생기면 먼저 Playwright 설치 상태와 폰트 설정을 확인하세요. 검증 스크립트는 대부분의 레이아웃 오류 위치를 찾는 데 도움이 됩니다.