Agent Skills 가이드
이 레포는 Claude Code, Cursor, Gemini CLI, Codex CLI에서 사용할 수 있는 Agent Skill 패키지입니다. GitHub Actions 자동화 템플릿과 더불어, 개발/DevOps Skill 14종을 제공합니다.
Skill이 뭔가요?
Skill은 특정 작업(예: 코드 리뷰, 이슈 작성, 리팩토링)에 특화된 지침과 출력 포맷을 가진 전문가 모드입니다. Claude Code에서는 /pro-<skill> 형태(예: /pro-review)로 호출하고, Gemini CLI는 extension, Codex CLI는 plugin marketplace를 통해 이 레포의 skills/를 읽습니다.
예를 들어 /pro-review를 실행하면 Claude가 단순히 "코드 좀 봐줘"에 답하는 게 아니라, 보안/성능/버그/품질/아키텍처/테스트 6가지 관점으로 나눠서 Critical/Major/Minor 우선순위로 정리된 리뷰를 돌려줍니다.
설치
Claude Code
claude plugin marketplace add Cassiiopeia/projectops
claude plugin install projectops@projectops-marketplace --scope user설치 후 Claude Code에서 /pro- 까지 입력하면 사용 가능한 Skill 목록이 자동완성됩니다.
Cursor
npx projectops의 skills 모드를 사용하면 skills/가 Cursor용 경로로 복사됩니다.
# macOS / Linux / Windows 공통
npx projectops --mode skills대화형 메뉴에서 Agent Skill 설치를 선택한 뒤 Cursor scope를 고르면 됩니다.
Gemini CLI
Gemini CLI는 extension으로 설치합니다.
gemini extensions install https://github.com/Cassiiopeia/projectops업데이트:
gemini extensions update projectops설치 후 Gemini는 루트 gemini-extension.json의 contextFileName에 따라 GEMINI.md를 읽고, skills/{skill-name}/SKILL.md를 참조합니다.
Codex CLI
Codex는 plugin marketplace source로 이 레포를 등록합니다. OpenAI 공식 marketplace 등재가 아니라, 사용자가 직접 신뢰한 GitHub repo를 marketplace source로 추가하는 흐름입니다.
방법 1 (기본): Plugin marketplace 등록
macOS / Linux:
codex plugin marketplace add Cassiiopeia/projectops마법사 설치:
npx projectops --mode skills마법사는 Codex marketplace를 등록합니다. 등록 후 /plugins에서 projectops 항목을 확인하세요.
업데이트:
codex plugin marketplace upgrade projectops방법 2 (Fallback): git clone + symlink로 즉시 활성화
marketplace 명령이 없거나 즉시 사용이 필요한 환경에서 사용합니다.
macOS / Linux:
git clone https://github.com/Cassiiopeia/projectops.git ~/.codex/projectops
mkdir -p ~/.agents/skills
ln -s ~/.codex/projectops/skills ~/.agents/skills/projectopsWindows PowerShell:
git clone https://github.com/Cassiiopeia/projectops.git "$env:USERPROFILE\.codex\projectops"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "%USERPROFILE%\.agents\skills\projectops" "%USERPROFILE%\.codex\projectops\skills"Codex에서는 slash command UI가 아니라 AGENTS.md와 설치된 skills/를 통해 관련 SKILL.md를 읽는 방식으로 사용합니다.
Skill 전체 목록 (14종)
용도에 따라 네 그룹으로 나뉩니다:
- 분석형 (1종) — 코드를 읽기만 하고 수정하지 않음. 계획/리뷰/진단 결과를 돌려줌.
- 구현형 (5종) — 실제로 파일을 수정하거나 생성함.
- 개발 사이클 자동화형 (3종) — 커밋, 배포, GitHub 작업을 대신 수행함.
- 문서/산출물 생성형 (5종) — 코드는 건드리지 않고,
.md파일이나 보고서를 생성함.
설계·계획·구현 흐름은 이 플러그인이 아니라
superpowers(brainstorming → writing-plans → executing-plans)가 담당합니다.
📊 분석형 Skill (1종)
코드를 수정하지 않습니다. "먼저 상황을 파악하고 싶을 때" 사용하세요.
/pro-review
무엇을 하나요? 코드를 보안/성능/버그/품질/아키텍처/테스트 6가지 관점으로 리뷰합니다. 발견한 이슈를 Critical / Major / Minor로 분류해서 돌려주고, 잘한 점도 같이 짚어줍니다.
수정되는 것: 없음 돌려주는 것: 우선순위별 리뷰 코멘트 + 개선 제안
언제 쓰나요?
- PR 올리기 전 셀프 리뷰
- 특정 파일이나 함수에 대한 2차 검토
- 구현 완료 후 "빠뜨린 거 없나?" 확인
🔧 구현형 Skill (5종)
실제로 파일을 수정합니다. "작업을 진행해달라"일 때 사용하세요.
/pro-figma
무엇을 하나요? Figma 시안을 코드로 옮기고, 옮긴 것이 시안과 같은지 셉니다. 덤프의 채움·테두리·효과·배치를 하나도 빠짐없이 나열해 작업 목록으로 삼고, 반응형 단위로 옮긴 뒤, 시안 그림과 앱 화면을 픽셀로 맞대 어긋난 자리를 짚어 줍니다.
수정되는 것: 해당 컴포넌트 파일 돌려주는 것: 분류표 + 반응형 코드 + 픽셀 대조 결과(차이 그림 포함)
언제 쓰나요?
- 디자이너가 전달한 화면을 코드로 옮길 때
- 옮긴 화면이 시안과 같은지 확인할 때
- 디자이너가 "이거 다른데요"라고 한 뒤 무엇이 다른지 특정할 때
옮기는 일과 세는 일이 한 스킬입니다. 나눠 두면 옮기는 쪽이 무엇을 옮겨야 하는지 모르는 채로 그림만 보고 만들게 됩니다 — 실제로 효과 네 줄 중 세 줄이 빠진 채 배포된 적이 있습니다.
/pro-oss-consult
무엇을 하나요? GitHub 레포를 오픈소스 프로젝트로서 진단합니다. 레포 성격(배포형 앱·작은 도구·CLI·문서·템플릿 등)을 먼저 판별하고, 첫인상·가치 증명·커뮤니티·코드 확장성·법적 안전·장기 운영 6축으로 깐깐하게 채점한 뒤, 성숙도 단계와 다음 단계 선행 조건을 알려줍니다. 사실 수집은 스크립트가, 판단은 에이전트가 합니다.
수정되는 것: 승인한 것만 — About·topics·Discussions·라벨(이 스킬의 CLI), 새 브랜치에 추가하는 문서 파일. 레포마다 계획을 보여주고 승인받으며, 가시성 변경·삭제·라이선스 교체는 하지 않고 제안만 합니다. 돌려주는 것: 진단 보고서(6축 점수·결함·개선안·성숙도), 계정 전체 일괄 점검이면 점수판
언제 쓰나요?
- 내 레포가 다른 사람에게 찾아가고 기여받을 만한 상태인지 점검할 때
- 막 공개한 레포의 공개 차단 사항(커밋된 비밀·라이선스·개인정보)을 확인할 때
- 계정이나 조직의 레포 전체를 한 번에 훑어 우선순위를 잡을 때
이슈·PR·댓글 작업 자체는
/pro-github, 코드 변경분 리뷰는/pro-review입니다.
/pro-init-worktree
무엇을 하나요? 브랜치명만 주면 Git worktree를 자동으로 생성하고, .gitignore를 분석해서 원본 프로젝트에 존재하는 로컬 설정 파일 후보를 찾습니다. 에이전트가 후보별 복사 필요성을 판단해 필요한 파일만 근거와 함께 선택 복사하고, 복사하지 않은 후보도 마지막에 리포트합니다. UTF-8 인코딩 문제도 처리합니다.
수정되는 것: 새 worktree 디렉토리 생성 + 필요한 로컬 설정 파일 선택 복사 돌려주는 것: 생성된 worktree 경로 + 복사/스킵/누락 후보 리포트
언제 쓰나요?
- PR마다 별도 worktree로 작업하고 싶을 때
.env, Firebase 설정, 서명 키, 로컬 빌드 설정처럼 worktree에도 필요한 파일을 놓치고 싶지 않을 때
/pro-launch
무엇을 하나요? 앱·웹·서버를 띄우고, 조작하고, 찍는 능력 스킬입니다. Android 에뮬레이터·iOS 시뮬레이터 화면을 상태바를 고정해 찍고, 브라우저를 열어 이동·클릭·입력·캡처합니다. 폭을 바꾸거나 API 응답을 바꿔치기해 빈 목록·실패·로딩 상태를 서버를 건드리지 않고 연출할 수 있습니다. 단건 HTTP 요청, DB 조회, 서버 로그도 적어 둔 접속 방법대로 실행합니다.
수정되는 것: 없음 (캡처와 실행 기록만 저장) 돌려주는 것: 캡처 이미지 + 실행 결과 JSON
언제 쓰나요?
- "에뮬레이터 띄워서 찍어줘", "모바일 폭으로 캡처해줘"
- 빈 목록·500 에러 같은 상태 화면이 필요할 때
- 다른 스킬(
pro-agent-test,pro-design-brief,pro-figma)이 화면을 찍어야 할 때
버그를 찾으며 끝까지 밟는 QA는
/pro-agent-test입니다. 이 스킬은 "띄우고 찍는 도구"입니다.
/pro-design-brief
무엇을 하나요? 시안보다 먼저 만든 화면을 디자이너에게 넘길 요청서를 만듭니다. 실제 화면을 상태별(빈 목록·실패·긴 글자·글자 크기·작은 폰)로 찍고, 배치 대안과 문구 후보, 꼭 지킬 것(브랜드 규격·합의된 예외)을 보드로 조립해 이슈·HTML 한 장·md 폴더 중 레포에 맞는 형식으로 넘깁니다. 정답이 아니라 생각할 재료를 줍니다.
수정되는 것: 없음 돌려주는 것: 상태별 캡처 보드 + 디자인 요청 이슈(또는 HTML/md)
언제 쓰나요?
- "디자인 요청해줘", "빈 화면이랑 에러 화면도 그려 달라고 해줘"
- 디자인 없이 먼저 만든 화면의 시안을 요청할 때
시안을 코드로 옮기고 대조하는 일은
/pro-figma입니다.
🔄 개발 사이클 자동화 Skill (3종)
이슈 등록부터 커밋, 배포까지 — 반복 작업을 AI가 대신합니다.
/pro-commit
무엇을 하나요?/pro-github의 이슈 생성이나 /pro-init-worktree가 저장해둔 이슈 컨텍스트(.projectops/context/current-issue.json)를 읽어서 프로젝트 커밋 컨벤션에 맞는 메시지를 자동 완성하고 커밋합니다. 메시지는 반드시 제안 후 사용자 확인을 받고 실행합니다.
수정되는 것: git 커밋 (staged 파일 기준)
돌려주는 것: 이슈제목 : 타입 : 변경사항 설명 이슈URL 형식의 완성된 커밋
커밋 컨벤션:
이슈제목 : feat : 변경사항 설명 https://github.com/.../issues/123이슈 컨텍스트가 없을 때:
- 이슈 새로 만들기 (
/pro-github이슈 생성 플로우 안내) - 이슈 번호 직접 입력 (GitHub에서 정보 자동 조회)
- 이슈 없이 자유 형식 커밋
- 취소
superpowers 원칙 준수:
- staged 파일 없으면
git add를 대신하지 않음 — 사용자가 직접 스테이징 - 사용자 확인 없이 절대 커밋 실행 안 함
git push는 절대 실행하지 않음 — 커밋까지만 담당
언제 쓰나요?
- 이슈 번호/URL을 커밋 메시지에 매번 복사붙여넣기하는 게 귀찮을 때
- 팀 커밋 컨벤션을 일관되게 유지하고 싶을 때
/pro-changelog-deploy
무엇을 하나요?develop 브랜치를 push 후 main으로 릴리스 PR(deploy PR)을 생성하고, 릴리스 노트를 직접 작성해서 PR 본문에 올립니다. PROJECT-COMMON-RELEASE-CHANGELOG 워크플로우가 "Summary by CodeRabbit" 문구를 감지하면 CHANGELOG 업데이트 후 automerge가 자동 진행됩니다. automerge에 실패하면 기존 PR을 닫고 새로 재시도합니다.
수정되는 것: 없음 (GitHub API 호출만) 돌려주는 것: develop → main 릴리스 PR(deploy PR) URL + 릴리스 노트 작성 완료 안내
언제 쓰나요?
- 구현 완료 후 배포 사이클 전체(push → PR → CHANGELOG → 머지)를 한 번에 처리하고 싶을 때
- automerge가 실패해서 재트리거가 필요할 때
/pro-github
무엇을 하나요? GitHub 이슈/PR/댓글을 독립적으로 조회하고 관리합니다. 다른 스킬 없이 단독으로 이슈 목록 조회, 상태 변경, 댓글 추가 등을 수행합니다. GitHub API를 직접 호출하며 gh CLI를 사용하지 않습니다.
수정되는 것: GitHub 이슈/PR 상태 (요청 시) 돌려주는 것: 이슈/PR 목록, 상세 정보, 작업 완료 안내
언제 쓰나요?
- 이슈 목록을 빠르게 조회하거나 상태를 바꾸고 싶을 때
- PR에 댓글을 추가하거나 라벨을 변경할 때
- 다른 스킬 없이 GitHub 작업만 단독으로 처리할 때
📝 문서/산출물 생성형 Skill (5종)
코드는 건드리지 않고, 특정 형식의 문서 파일을 생성합니다.
/pro-report
무엇을 하나요?git status로 변경 파일을 확인하고, 이슈 기반으로 관련 파일을 선별해서 읽은 뒤 구현 보고서를 작성합니다. .report/YYYYMMDD_#이슈번호_설명.md 형식으로 저장됩니다.
수정되는 것: .report/ 폴더에 새 .md 파일 돌려주는 것: 개요/변경사항/주요 구현 내용/주의사항이 정리된 보고서
언제 쓰나요?
- 구현 완료 후 PR 설명이나 내부 보고서가 필요할 때
- 특정 이슈에 대한 작업 내역 정리
/pro-testcase
무엇을 하나요? GitHub 이슈를 읽고 관련 코드를 탐색한 뒤, QA용 테스트 체크리스트를 생성합니다. 기본 기능/엣지 케이스/프로젝트 타입별 추가 항목이 포함됩니다. 결과는 testcase-[번호]-[설명].md로 저장되어 GitHub 댓글에 바로 붙여넣을 수 있습니다.
수정되는 것: 테스트케이스 .md 파일 돌려주는 것: 체크박스 형식의 QA 테스트 항목 목록
언제 쓰나요?
- QA에게 넘기기 전 체크리스트가 필요할 때
- 수동 테스트 시나리오를 정리하고 싶을 때
/pro-agent-test
무엇을 하나요? 앱·웹·서버를 실제로 실행해 밟으며 버그를 찾는 QA입니다. 화면을 누르고(앱·웹) 요청을 보내며(서버), 단계마다 기기 저장소·브라우저 상태·서버 DB를 대조합니다. 요청받은 자리만 보지 않고 같은 성격의 다른 화면·대칭 동작(가입↔탈퇴, 생성↔삭제)도 함께 확인해 일관성 결함을 찾습니다. 로그가 없으면 그것을 추적 불가 결함으로 보고합니다.
수정되는 것: 없음 (코드를 고치지 않고 결함만 보고) 돌려주는 것: 단계별 근거(스크린샷·대조표) · 재현 절차 · 심각도별 결함 목록
언제 쓰나요?
- 배포 전 주요 흐름(로그인·가입·결제)이 진짜 되는지 확인
- 사용자가 겪은 버그 재현 — 유닛 테스트로 안 잡히는 것들
- 릴리스 빌드에서만 나는 문제 (R8·서명·manifest는 debug에서 재현되지 않는다)
/pro-testcase(QA 문서 생성)와 다릅니다 — 이 skill은 앱을 실행합니다.
/pro-ssh
무엇을 하나요? AWS EC2, 시놀로지 NAS, 일반 Linux 서버 등 SSH 접근 가능한 모든 서버에 접속해서 명령을 실행하고 결과를 보고합니다. 비밀번호 인증과 PEM 키 인증을 모두 지원하며, 서버 정보는 ~/.projectops/config/ssh.config.json에 저장해두면 이름만 말해도 바로 접속합니다.
수정되는 것: 없음 (원격 서버에서 명령 실행 후 결과만 반환) 돌려주는 것: SSH 명령 실행 결과 + 요약 보고
언제 쓰나요?
- "서버 로그 봐줘", "prod 검수해줘", "배포 됐는지 확인해줘"
- CI/CD 완료 후 서버 상태 자동 검수
- 여러 서버를 config에 등록해두고 이름으로 선택
/pro-skill-creator
무엇을 하나요? Skill 파일을 생성(CREATE)·리뷰(REVIEW)·개선(IMPROVE) 3가지 모드로 관리합니다. CREATE는 새 SKILL.md를 표준 포맷으로 작성하고, REVIEW는 기존 Skill을 common-rules.md 기준으로 검토해 개선점을 제안하며, IMPROVE는 리뷰 결과를 반영해 실제로 수정합니다.
수정되는 것: skills/{skill-name}/SKILL.md (IMPROVE 모드 시) 돌려주는 것: 새 SKILL.md 초안 / 리뷰 리포트 / 개선된 SKILL.md
언제 쓰나요?
- 새 Skill을 표준에 맞게 처음부터 만들고 싶을 때
- 기존 Skill이 최신 컨벤션과 맞는지 검토할 때
- 리뷰 결과를 바로 Skill에 반영하고 싶을 때
나에게 맞추기 (Make it yours)
Skill이 내 스타일로 씁니다. 선호는 ~/.projectops/config/config.json에 적습니다. 첫 실행 때 묻지 않으며, 비어 있으면 각 Skill의 기본 동작입니다.
{
"preferences": { "language": "ko", "tone": "짧고 단정하게", "rules": ["이모지 금지"] },
"skills": { "pro-commit": { "preset": "gitmoji" } }
}- 적용 순서(뒤가 이김):
preferences→skills.<skill-id>→github.repos[].preferences→github.repos[].skills.<skill-id>. /pro-commit의 형식 우선순위: 팀version.yml의issue_helper.commit_template→ projectops가 설치된 레포의 projectops 형식 → 내template→ 내preset(기본conventional, 그 외projectops·gitmoji·custom).- 선호는 표현만 바꿉니다. 승인 게이트, 시크릿 보호,
--dry-run, push 금지는 끌 수 없습니다. - 자세히:
skills/references/preferences.md
Extras (선택 플러그인)
/pro-synology-expose(시놀로지 NAS 서비스를 외부 도메인으로 노출하는 가이드)와 /pro-code-consult(AI가 짠 코드를 코딩 규칙에 맞게 점검·리팩터링하고, 변경분마다 낡은 주석·중복을 검사하며, 기존 위반을 동결 목록으로 묶어 줄여 가는 스킬)는 코어 플러그인에 없고 선택 플러그인 projectops-extras에 있습니다.
# Claude Code
claude plugin install projectops-extras@projectops-marketplace --scope user
# Codex CLI: `codex plugin marketplace add Cassiiopeia/projectops` 후 플러그인 목록에서 projectops-extras 설치Cursor·Gemini CLI·pi에는 extras 설치 경로가 없고, npx projectops 동기화 때 이 스킬이 제거됩니다. 계속 쓰려면 레포의 plugins/projectops-extras/skills/<스킬 폴더>와 plugins/projectops-extras/skills/references/를 둘 다 직접 복사하세요.
개인 설정(언어·말투·규칙)을 읽는 prefs_cli.py는 코어 플러그인에 들어 있습니다. extras만 설치하면 설정을 찾지 못해 기본값으로 동작합니다. 개인 설정을 쓰려면 코어 플러그인도 함께 설치하세요.
어떤 Skill을 언제 쓸까?
실제 작업 순서는 이슈 등록 → 작업 환경 분리 → 계획 → 구현 → 테스트 → 리뷰 → 보고서 입니다.
표준 개발 흐름 (전체 사이클)
flowchart TD
A(["작업 시작"]) --> B["/pro-github<br/>이슈 등록"]
B --> C["/pro-init-worktree<br/>worktree + 민감파일 복사"]
C --> D{"작업 유형?"}
D -->|새 기능·설계·리팩토링| E1["superpowers:brainstorming<br/>무엇을 왜 만들지 확정"]
D -->|버그·장애| E2["superpowers:systematic-debugging<br/>원인 조사"]
E1 --> F1["superpowers:writing-plans<br/>구현 계획 수립"]
F1 --> G1["superpowers:executing-plans<br/>계획 실행"]
E2 --> G1
G1 --> H["/pro-review<br/>셀프 리뷰"]
H --> I["/pro-commit<br/>이슈 연동 커밋"]
I --> J["/pro-report<br/>구현 보고서 + GitHub 댓글"]
J --> K(["PR 등록"])
K --> L["/pro-changelog-deploy<br/>릴리스 PR + automerge"]시나리오별 흐름 정리
| 상황 | 추천 흐름 |
|---|---|
| 새 기능 개발 (표준) | pro-github → pro-init-worktree → brainstorming → writing-plans → executing-plans → pro-review → pro-commit → pro-report → pro-changelog-deploy |
| 버그 수정 | pro-github → pro-init-worktree → systematic-debugging(원인 조사) → executing-plans → pro-commit → pro-report → pro-changelog-deploy |
| 리팩토링·설계 변경 | 새 기능 개발과 동일 (brainstorming에서 범위를 좁혀 시작) |
| QA 테스트케이스 | pro-github → pro-testcase |
| 실제 실행 검증(앱·웹·서버) | pro-agent-test → (문제 발견 시) pro-github → pro-commit |
단건 작업 (사이클 없이 단독 호출)
| 상황 | 사용 Skill |
|---|---|
| 코드 리뷰만 필요 | review |
| 이슈만 빠르게 초안 작성 | github |
| PR 설명 / QA 체크리스트 생성 | report / testcase |
| Figma 디자인을 코드로 옮기고 시안과 대조 | figma |
| 원격 서버 SSH 접속·명령 실행 | ssh |
| 배포 PR 생성 + automerge | changelog-deploy |
| GitHub 이슈/PR 조회 및 관리 | github |
| Skill 생성/리뷰/개선 | skill-creator |
참고
- Skill 원본: 이 레포의
skills/폴더 (Claude/Gemini/Codex/Cursor 공통 원본) - Claude Code 매니페스트:
.claude-plugin/plugin.json,.claude-plugin/marketplace.json - Gemini CLI 매니페스트:
gemini-extension.json,GEMINI.md - Codex CLI marketplace/bootstrap/metadata:
.agents/plugins/marketplace.json,AGENTS.md,.codex-plugin/plugin.json - 버전 동기화:
version.yml변경 시PROJECT-TEMPLATE-PLUGIN-VERSION-SYNC워크플로우가 자동 반영