이 레포가 무엇을 하는 물건인가.
플러그인은 매니페스트(plugin.json) 하나로 시작해, 필요에 따라 스킬(skills/)·앱 연동(.app.json)·MCP 서버(.mcp.json)·전문 에이전트(agents/)·슬래시 커맨드(commands/)·훅(hooks.json)을 조합합니다. 단순한 것(스킬 1개)부터 풍부한 것(Figma — 에이전트 4종+커맨드 4종+훅+검증 스크립트)까지 난이도 스펙트럼이 한 레포에 있습니다.
눈에 띄는 건 라인업의 폭입니다. SaaS 연동(Notion·Airtable·Asana·Box·Calendly), 디자인(Figma·Canva·BioRender), 인프라(Cloudflare·CircleCI·Netlify), 금융(Binance·Alpaca·Brex), 그리고 서비스가 아닌 워크플로 플러그인(build-ios-apps·build-web-apps·build-web-data-visualization)까지 — "특정 API 연동"과 "작업 방식 패키징" 양쪽 모두 플러그인이 될 수 있음을 보여줍니다.
트렌딩 이유 · 경쟁 대비 장점.
에이전트 플러그인 생태계는 Claude Code 플러그인·MCP·각사 스킬 규약이 난립하며 "어떤 구조가 표준이 될까"가 초미의 관심사입니다. 이 레포는 OpenAI가 파트너들과 함께 제시하는 공식 규약 + 대량의 실물 예제라는 점에서, Codex 사용자가 아니어도 플러그인 설계자라면 들여다볼 가치가 있습니다 — Claude Code 플러그인을 만들던 사람이 구조 비교용으로 읽기에도 좋습니다.
| 비교 항목 | 흩어진 커뮤니티 예제 | openai/plugins |
|---|---|---|
| 규약 일관성 | 레포마다 제각각 | 173개가 같은 매니페스트 스키마 |
| 품질 신호 | 알 수 없음 | OpenAI 큐레이션 + 벤더 공식 제작 다수 |
| 난이도 스펙트럼 | 단편적 | 스킬 1개짜리부터 멀티 에이전트+훅까지 |
| 평가 데이터 | 거의 없음 | 일부 스킬에 evaluations/ JSON 동봉 |
문서는 스키마를 알려주지만, 실제 좋은 플러그인의 살(스킬 문장, 레퍼런스 구성, 훅 사용처)은 보여주지 못합니다.
내가 만들려는 것과 가장 닮은 플러그인을 찾아 폴더째 복사해 고치면 됩니다 — 예제 주도(example-driven) 생태계 부트스트랩 전략.
코드보다 규약 — 플러그인 표면(surface) 7종.
| 표면 | 파일 | 역할 |
|---|---|---|
| 매니페스트 | .codex-plugin/plugin.json (필수) | 이름·버전·설명·키워드 + interface(표시명·카테고리·능력) — 마켓 노출 메타데이터까지 포함. |
| 스킬 | skills/*/SKILL.md | 워크플로 본체. references/·examples/·evaluations/ 동반 가능. |
| 앱 연동 | .app.json | ChatGPT 앱(커넥터) 연계 선언. |
| MCP | .mcp.json | 외부 MCP 서버 연결 — API 호출이 필요한 플러그인의 손발. |
| 에이전트 | agents/*.md + openai.yaml | 전문 페르소나 (예: Figma의 design-parity-review-agent). |
| 커맨드 | commands/*.md | 슬래시 커맨드 진입점 (예: /implement-from-figma). |
| 훅 | hooks.json + scripts/*.sh | 이벤트 개입 (예: Figma의 쓰기 후 디자인 일치 검사 스크립트). |
잘 만든 플러그인 하나(Figma)를 해부한다.
흐름 하나를 따라가면 — /implement-from-figma: ① 사용자가 커맨드를 치면 ② figma-implementation-agent가 소환되고 ③ 그 에이전트는 skills/의 절차(컴포넌트 매핑 → 토큰 추출 → 구현)와 references/(Figma API 사용법)를 따라 코드를 만듭니다. ④ 파일이 써질 때마다 hooks.json에 등록된 parity-check 스크립트가 돌아 "구현이 디자인과 일치하는가"를 자동 검사합니다. 진입(커맨드) → 위임(에이전트) → 절차(스킬) → 강제(훅)의 4층이 분리돼 있어서, 각 층만 고쳐도 동작이 바뀝니다.
레스토랑 프랜차이즈 매뉴얼에 비유하면 — 메뉴판(커맨드), 담당 셰프(에이전트), 레시피(스킬), 위생 점검 규정(훅)이 분리된 구조입니다. 이 레포는 그런 매뉴얼 173개를 모은 본사 자료실이죠.
어떤 폴더가 무슨 일을 하나.
| 읽기 코스 | 추천 이유 |
|---|---|
| ① notion/ | 스킬 중심 플러그인의 정석 — 예제·레퍼런스·평가의 3종 세트. |
| ② figma/ | 모든 표면(커맨드·에이전트·스킬·훅·스크립트)을 쓰는 최대 구성. |
| ③ build-web-apps/ | 특정 서비스 없이 "작업 방식"만 패키징하는 법. |
| ④ 아무 단순 플러그인 | 최소 구성(매니페스트+스킬 1개)이 어디까지 작은지 확인. |
이 레포에서 배울 만한 것 + 어디를 보면 되는지.
plugin.json의 interface 블록(displayName·category·capabilities)은 "마켓플레이스 노출"까지 고려한 메타데이터 설계입니다. 패키지 매니페스트(npm package.json)가 걸어온 길을 에이전트 플러그인이 어떻게 반복하는지 비교해 보세요.
Figma 플러그인의 계층 분리는 Claude Code 플러그인을 만들 때도 그대로 통하는 구조입니다. 특히 "쓰기 후 자동 검증 훅"은 에이전트 출력 품질 보증의 실전 패턴.
스펙 문서가 아니라 베낄 수 있는 실물의 양으로 규약을 보급하는 전략 — 자사 생태계를 키워야 하는 입장이라면 이 레포 자체가 케이스 스터디입니다.
notion-knowledge-capture의 평가 JSON은 입력 시나리오와 기대 산출을 정의합니다. 내 스킬에도 같은 형식의 회귀 케이스를 붙이는 출발점으로 좋습니다.
돌리려면 무엇이 필요한가.
| 항목 | 요구사항 |
|---|---|
| 실행 환경 | Codex CLI (플러그인 기능 지원 버전) — 플러그인을 실제 구동할 경우. |
| 읽기만 할 경우 | 없음 — 전부 마크다운·JSON이라 브라우저로 충분. |
| 개별 플러그인 | 해당 서비스 계정/MCP 서버 (예: Figma 플러그인은 Figma 액세스). |
| 클론 팁 | 약 4,900 파일 — 특정 플러그인만 보려면 sparse-checkout 권장. |
난이도별로 손에 익히는 단계.
notion(스킬형)·figma(풀구성)·아무 단순 플러그인 하나를 골라 plugin.json과 폴더 구성을 표로 비교해 봅니다 — 표면 7종이 어떻게 조합되는지 감 잡기.
자주 쓰는 서비스(또는 사내 도구) 하나를 골라, 가장 닮은 기존 플러그인을 복사해 매니페스트·스킬을 내 것으로 바꿔 봅니다. 커밋 전 기존 173개의 네이밍·구성 관례를 따르는지 점검.
같은 목적의 플러그인을 이 레포(Codex 규약)와 Claude Code 플러그인 규약으로 나란히 분석해, 매니페스트·스킬·훅 규약의 공통점/차이를 정리합니다 — 멀티 생태계 시대의 필수 감각.
notion의 evaluations/ 형식을 본떠, 실습 2에서 만든 스킬에 평가 JSON 3개를 붙이고 실제로 에이전트 출력을 채점해 봅니다.
한 주씩 따라가는 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | 플러그인 해부 — 표면 7종 이해 | README · 실습 1 |
| 2주차 | 스킬 작법 — 좋은 SKILL.md의 구성 | notion·figma의 skills/ 정독 |
| 3주차 | MCP 연동 플러그인 분석 | .mcp.json 쓰는 플러그인들 grep |
| 4주차 | 내 플러그인 제작·검증 | 실습 2·4 |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| Codex | OpenAI의 코딩 에이전트 CLI — 이 플러그인들의 숙주. |
| 플러그인 매니페스트 | plugin.json — 플러그인의 신원·구성·마켓 노출 정보를 담은 필수 파일. |
| 표면(surface) | 플러그인이 노출하는 기능 통로 — 스킬·커맨드·에이전트·훅·MCP·앱. |
| SKILL.md | 에이전트가 따르는 절차 문서 — 플러그인의 지식 본체. |
| 워크플로 플러그인 | 특정 서비스가 아니라 작업 방식(iOS 앱 빌드 등)을 패키징한 플러그인. |
| Code Connect | Figma 컴포넌트와 실제 코드 컴포넌트를 연결하는 Figma 기능. |
| design parity | 구현 결과와 디자인 원본의 일치도 — 훅으로 자동 검사하는 예가 있음. |
| evaluations | 스킬 동작을 검증하는 입력/기대 산출 케이스 — 스킬의 테스트. |
| sparse-checkout | 대형 레포에서 필요한 폴더만 받는 git 기능. |