2026년 4월 24일 | 개발 깨알 상식_Tips
Codex의 Plugins and skills 문서와 OpenAI Developers skills 문서를 같이 보다가, 내가 그동안 skill과 plugin을 거의 같은 상자처럼 취급하고 있었다는 걸 뒤늦게 깨달았다. 둘 다 에이전트 성능을 키우는 장치처럼 보이지만, 실제로는 역할이 꽤 다르다. skill은 팀 절차를 적는 층이고, plugin은 외부 도구와 데이터를 연결하는 층이다. 이 경계를 먼저 나눠 놓으면 바이브코딩할 때 프롬프트가 덜 비대해지고, 연결 문제와 작업 절차 문제도 덜 섞인다.
나는 예전에는 외부 문서나 메일함을 읽게 해야 할 일이 생기면 일단 plugin부터 떠올렸다. 그런데 이렇게 시작하면, 작업 순서와 출력 형식, 검증 규칙까지 연결 계층에 같이 달라붙으면서 구조가 금방 흐려진다. 반대로 먼저 skill로 우리 팀이 이 작업을 어떤 순서로 끝내는지를 고정해 두면, 나중에 Google Drive든 Slack이든 붙일 데이터 통로만 별도로 바꾸면 된다. OpenAI Academy가 4월 23일 문서에서 말한 "skill은 process, plugin은 connected tool"이라는 구분이 실전에서 바로 먹히는 이유가 여기 있다.
Figure 1: 절차는 skill, 외부 연결은 plugin, 반복 실행은 automation으로 나누면 에이전트 구성이 덜 꼬인다.
이 그림에서 중요한 건 순서다. 반복되는 작업이 보이면 먼저 skill로 절차를 얇게 고정하고, 그 절차가 외부 자료를 꼭 필요로 할 때만 plugin을 붙인다. 그 다음 결과 형식이 충분히 안정됐을 때 automation으로 주기 실행을 올리는 편이 안전하다. 연결과 절차를 한 번에 묶으면 에이전트가 왜 실패했는지 원인을 좁히기 어려운데, 이 셋을 분리하면 어디가 문제인지 바로 보인다.
내가 바로 써먹기 좋다고 느낀 건 Developers 문서의 progressive disclosure 설명이었다. Codex는 skill을 처음부터 전부 읽지 않고, name / description / file path 같은 메타데이터를 먼저 보고 필요하다고 판단할 때만 `SKILL.md` 본문을 읽는다. 그래서 skill을 만들 때 핵심은 설명을 길게 쓰는 게 아니라, 언제 트리거되어야 하는지와 언제 쓰면 안 되는지를 description에 선명하게 적는 것이다. 여기서 경계가 흐리면 skill이 안 불리거나, 반대로 엉뚱한 작업에 불려 나오는 일이 생긴다.
customer-update/
├── SKILL.md
├── references/
│ └── report-format.md
└── scripts/
└── build_update.py
이런 식으로 시작하면 된다. SKILL.md에는 절차와 경계만 남기고, 길게 참조해야 하는 문서는 `references/`, 반복 실행이 필요한 확정 로직은 `scripts/`로 빼는 구조다. OpenAI Developers 문서도 skill 디렉터리를 `SKILL.md + scripts/ + references/ + assets/` 조합으로 설명한다. 한 파일 안에 모든 배경과 예시를 우겨 넣는 방식보다, 에이전트가 필요할 때만 더 읽게 만드는 구조가 훨씬 덜 무겁다.
---
name: customer-update
description: 주간 고객 업데이트를 만들 때 사용한다. 내부 메모를 표준 형식으로 정리하고,
초안 작성까지만 맡는다. 외부 발송이나 승인 단계에는 쓰지 않는다.
---
1. notes 폴더와 references/report-format.md를 먼저 읽는다.
2. 빠진 데이터가 있으면 어떤 자료가 비었는지 먼저 표시한다.
3. 최종 출력은 팀 표준 섹션 순서를 지킨다.
이 예시에서 내가 일부러 넣은 문장이 마지막 줄이다. "어디까지 하고 어디서 멈추는가"를 적어 두면, skill이 프롬프트 대용 장문이 아니라 작업 계약으로 바뀐다. 그리고 외부 CRM, Drive, 메일함을 읽어야 한다면 그때 plugin을 붙이면 된다. 즉 skill이 절차를 잡고, plugin은 데이터를 가져오는 통로만 맡는다. 둘을 뒤섞지 않으면 나중에 연결 대상을 바꿀 때도 skill 본문을 크게 안 건드려도 된다.
여기서 한 번 더 중요해지는 게 호출 방식이다. Developers 문서는 skill이 명시 호출과 암시 호출 두 방식으로 켜질 수 있다고 설명한다. 직접 쓸 때는 `/skills`로 목록을 보고 `$customer-update`처럼 부를 수 있지만, 실제로 더 자주 쓰게 되는 건 description 기반 암시 호출이다. 그래서 이름을 멋있게 짓는 것보다 어떤 입력에서 불려야 하는지, 어떤 단계에서는 불리면 안 되는지를 description에 적는 편이 훨씬 중요하다. 이걸 빼먹으면 skill은 있는데도 안 쓰이거나, 반대로 뜬금없는 곳에 불려와 결과를 망친다.
/skills
$customer-update 이번 주 notes 폴더를 바탕으로 고객 업데이트 초안을 만든다
$skill-installer linear
내가 요즘 이 순서를 특히 강조하는 건, 많은 팀이 반복 절차까지 plugin 안에 같이 밀어 넣는 실수를 하기 때문이다. 예를 들어 "Drive에서 파일 읽기 → usage 확인 → 리스크 메모 → 요약 템플릿 채우기" 같은 흐름은 사실 연결 문제가 아니라 절차 문제다. 이걸 plugin 설명이나 커넥터 설정에 같이 박아 두면, 다른 데이터 소스로 갈아탈 때마다 로직까지 같이 뜯어고쳐야 한다. 반대로 절차는 skill에 두고, Drive나 Slack 같은 입구만 plugin으로 바꾸면 같은 작업 방식을 훨씬 오래 재사용할 수 있다.
공개된 openai/skills 저장소를 봐도 이 감각이 드러난다. 저장소는 4월 24일 오전 기준으로 17,351 stars를 기록하고 있었고, `.system` 아래에 `skill-creator`, `plugin-creator`, `skill-installer`를 따로 둔다. 이 분리가 꽤 중요하다. OpenAI 쪽도 skill 작성과 plugin 포장을 같은 작업으로 취급하지 않는다는 뜻이기 때문이다. 내 기준에서는 이 구조만 봐도 plugin부터 만들기보다, 먼저 skill 경계를 또렷하게 적는 편이 맞다는 쪽으로 결론이 난다.
또 하나 괜찮았던 포인트는 배포 경계다. Developers 문서는 repo 안에서 로컬로 바로 쓰는 skill 폴더와, 여러 skill이나 앱 연동을 묶어 배포하는 plugin을 분리해 설명한다. 이 말은 곧, 처음부터 배포 포맷으로 과하게 설계하지 말고 내 저장소 안에서 잘 도는 작은 skill부터 만든 뒤, 정말 재사용 범위가 커졌을 때만 plugin으로 감싸라는 얘기다. 실무에서는 이 순서가 생각보다 중요하다. 처음부터 큰 포장 단위를 만들면 검증해야 할 표면이 너무 넓어지는데, skill부터 만들면 실패 범위를 훨씬 작게 유지할 수 있다.
- 같은 작업을 두세 번 반복했다면, 새 plugin을 만들기 전에 먼저 skill로 절차를 빼 둔다.
- description에는 언제 쓰는지뿐 아니라 언제 쓰지 않는지도 적는다.
- 긴 배경 설명은 `references/`로 보내고, 확정 로직만 `scripts/`에 둔다.
- Drive, 이메일, Slack 같은 외부 자료가 꼭 필요할 때만 plugin을 붙인다.
- 결과 형식이 충분히 안정된 뒤에만 automation으로 주기 실행을 올린다.
바이브코딩에서 자주 헷갈리는 건 "에이전트가 어디에 연결되느냐"와 "에이전트가 우리 방식대로 일하느냐"를 같은 문제로 보는 순간이다. 연결은 plugin이 해결하고, 팀 절차는 skill이 해결한다. 이 둘을 먼저 갈라 놓으면 프롬프트가 덜 길어지고, 디버깅도 쉬워진다. 다음에 Codex나 비슷한 작업형 에이전트를 붙일 일이 있으면, 일단 plugin부터 만들지 말고 이건 연결 문제인지, 절차 문제인지부터 나눠 보는 쪽이 훨씬 덜 꼬인다.