기여와 배포
원본과 생성물 구분, 스킬 작성 규칙, PR 제출과 릴리스·문서 배포 확인
목표: 검증한 수정 사항을 PR로 공유하고 실제 문서 사이트에 반영됐는지 확인합니다. 작은 기여도 첫 수정 → 검증의 순서는 같습니다.
어디를 고치나요?#
| 바꿀 내용 | 원본 | 이어서 갱신/확인할 것 |
|---|---|---|
| AI가 따르는 스킬 | plugins/cc-이름/skills/스킬이름/SKILL.md |
관련 참조·예제, 메타데이터 검사 |
| 커맨드·에이전트·규칙 | 해당 플러그인의 commands/, agents/, rules/ |
설명/호출명/참조와 설치 도구별 지원 |
| 사람용 입문 문서 | docs_site/content/의 최상위 .md |
문서 생성·빌드·링크 검사 |
| 플러그인 메타데이터 | .claude-plugin/marketplace.json, 각 .claude-plugin/plugin.json |
scripts/sync_codex_plugins.py --write |
| 분류·프리셋 | taxonomy.json |
scripts/sync_taxonomy.py --write |
docs_site/content/plugins/는 generate_docs.py가 만드는 결과입니다.
.codex-plugin/plugin.json, .agents/plugins/marketplace.json,
orca-*.json도 생성물입니다.
OpenCode 변환 산출물은 설치 시 생성하며 저장소에 커밋하지 않습니다.
스킬 작성의 기본#
plugins/cc-이름/
├── .claude-plugin/plugin.json
├── README.md
├── skills/스킬이름/SKILL.md
├── commands/
├── agents/
└── rules/
처음에는 기존 플러그인의 스킬 하나를 개선하세요.
REFERENCE.md·TEMPLATES.md는 자료가 커졌을 때 나누는 선택 사항입니다.
- 스킬
name은 폴더명과 같고, 전체 저장소에서 고유해야 합니다. - 스킬
description에는 어떤 작업에서 쓸지 적습니다. - 커맨드 설명은 무엇을 하는지 + 무엇이 남는지 + 언제 고르는지를 적습니다.
- 준비물·입력·절차·완료 기준·실패 처리·출처를 본문에서 확인할 수 있게 합니다.
- 새 플러그인·이름 변경은 관련 카탈로그와 참조까지 검증합니다.
plugin.json의 허용 필드#
다음은 형식 예시입니다. 실제 플러그인명과 기존 버전을 사용합니다.
{
"name": "cc-example",
"version": "1.0.0",
"description": "예시 작업을 안내하는 플러그인"
}
허용 필드는 이 세 개뿐입니다. skills, commands, agents, rules
배열을 추가하지 않습니다.
디렉토리는 관례로 인식됩니다. 플러그인 버전과 marketplace의 해당 엔트리는 일치해야 합니다.
세부 규칙의 원본은 CONTRIBUTING.md입니다.
PR 제출 순서#
PR(Pull Request)은 “이 변경을 합쳐 주세요”라는 검토 요청입니다. 터미널 · 저장소 루트, 내 작업 브랜치에서:
git status --short
git diff --check
git diff -- plugins/cc-compass/skills/cocode-compass/SKILL.md검증 체크리스트를 통과한 뒤 실제로 바꾼 파일만 선택합니다.
git add plugins/cc-compass/skills/cocode-compass/SKILL.md
git commit -m "docs(cc-compass): 추천 결과의 준비물 확인 기준 개선"
git push -u origin HEAD
gh pr create --base main
정상 결과: PR URL이 만들어지고 GitHub에서 diff와 검사 상태를 볼 수 있습니다.
원격 push 권한이 없다면 관리자에게 기여 경로를 요청하세요.
Epic 안에서 작업한다면 main 대신 해당 부모 작업 브랜치를 PR base로 사용합니다.
/cc-dev:go 자동화는 이슈·브랜치·부모 관계와 머지 승인을 관리합니다.
PR 본문에 다음을 적습니다.
- 변경 이유와 관련 이슈 (
Closes #번호는 연결할 이슈가 있을 때) - 바꾼 스킬/문서와 읽어볼 순서
- 실행한 검사 명령과 결과, 변경 전후의 동작 확인
- 미검증 환경과 필요한 후속 확인
검사 실패는 문제 해결로 해결하고 같은 PR에 수정 커밋을 올립니다. 머지는 팀의 리뷰·권한 정책에 따라 진행합니다.
머지 뒤 자동으로 일어나는 일#
| 흐름 | 역할 | 성공 증거 |
|---|---|---|
| Auto Version | main의 커밋 메시지로 버전·변경 기록·태그 갱신 | 워크플로 결과와 release 커밋 |
| Create GitHub Release | 태그와 버전 일치 확인 후 릴리스 생성 | GitHub Releases |
| Deploy Docs | 문서 생성·테스트·Jaspr 빌드·다운로드 패키징·Pages 배포 | 해당 실행의 deploy 성공 + 실제 페이지 |
현재 docs:·fix:·perf:·refactor:는 patch, feat:는 minor,
명시적 breaking 변경은 major 후보입니다. 최종 squash 커밋 메시지가 기준이 되므로 PR 제목도 확인합니다.
일반 기여에서 버전을 임의로 여러 곳에 직접 올리기보다 자동화 결과를 확인하세요.
버전 판정 원본은 .github/scripts/detect_bump.sh, 배포 트리거 원본은 .github/workflows/입니다.
Auto Version의 release 커밋은 [skip ci]를 사용하고 후속 Deploy Docs를 명시적으로 실행합니다.
main push 자체는 Deploy Docs를 띄우지 않습니다. 릴리스가 없는 머지(chore·ci 등)도
사이트 입력(docs_site·plugins·scripts)이 바뀌었으면 Auto Version이 같은 방식으로 배포합니다.
PR 검사 성공만으로 배포 성공이라 판단하지 않습니다.
PR 여러 개가 잇달아 머지되면 앞 Auto Version 실행이 "main 이 움직여 … 올리지 않았습니다" 오류로 실패하거나 대기 중에 취소될 수 있습니다. 그 실행의 커밋은 다음 실행이 이어받아 함께 릴리스하므로, 다음 실행의 release 커밋과 CHANGELOG 에 내 PR 이 들어 있는지 확인합니다.
실제 배포 확인 (기여자·유지관리자)#
터미널 · 저장소 루트에서:
gh run list --workflow version.yml --limit 5
gh run list --workflow deploy-docs.yml --limit 5
gh release list --limit 3
표의 실행을 열어 내 변경을 포함한 커밋인지, build뿐 아니라 deploy도 성공했는지 확인합니다.
실행 번호를 선택해 gh run view 실행번호 --web으로 볼 수 있습니다.
그다음 브라우저에서:
- 문서 사이트에서 바꾼 페이지로 이동하고 새 문장을 확인합니다.
- 링크·코드 블록을 확인하고, 좁은 화면에서도 메뉴와 본문이 읽히는지 봅니다.
- manifest.json의 전체/플러그인 버전을 변경 기록과 대조합니다.
- 설치 파일도 바꿨다면 다운로드한 아카이브의 해당 파일을 확인합니다.
유지관리자가 재배포할 때: main의 검증된 상태와 권한을 확인한 뒤 실행합니다.
gh workflow run deploy-docs.yml --ref main명령이 접수됐다는 것만으로 완료가 아닙니다. 위 실행 목록과 공개 페이지를 다시 확인합니다.
로컬 미리보기: docs_site 운영 가이드 에서 현재 CI와 같은 생성·빌드 명령을 확인할 수 있습니다.
완료: 원본 수정 → 검증 → PR 리뷰·머지 → 배포 성공 → 새 페이지/설치본 확인.
다음: 전체 스킬 찾아보기 · 막힌 곳 해결하기