AI 에이전트를 개발하다 보면 프롬프트가 점점 길어지고 복잡해지는 문제를 겪게 됩니다. 재사용 가능한 워크플로우를 어떻게 관리할 것인가? OpenAI가 이 문제에 대한 답으로 Skills를 API에 도입했습니다.

출처: Skills in OpenAI API – OpenAI Developer Documentation

Skills란 무엇인가

Skills는 재사용 가능한 절차(instructions + scripts + assets)를 하나의 패키지로 묶은 것입니다. 마치 작은 CLI 도구처럼 동작하죠. SKILL.md 파일을 중심으로 관련 스크립트와 리소스를 폴더에 담아 배포하면, 모델이 필요할 때만 이를 불러와 실행합니다.

Anthropic이 2025년 10월에 처음 소개하고 이후 Agent Skills라는 오픈 스탠다드로 공개한 개념입니다. 핵심은 “폴더 하나에 마크다운 파일과 스크립트”라는 극도로 단순한 설계죠.

OpenAI는 프롬프트, 툴, Skills를 3층 구조로 구분합니다:

• 프롬프트: 항상 적용되는 전역 행동과 제약 (예: 안전 정책, 톤)
• 툴: 외부 서비스 호출이나 부수 효과 발생 (예: 이메일 전송, 주문 취소)
• Skills: 필요할 때만 실행되는 패키징된 절차

Skills는 특히 이런 상황에 적합합니다: 반복 가능한 워크플로우를 여러 에이전트나 팀에서 공유할 때, 복잡한 분기 로직이 필요할 때, 버전 관리가 중요할 때. 예를 들어 회사 표준 보고서 생성 절차나 데이터 정제 파이프라인 같은 것들이죠.

Simon Willison은 “Agent Skills가 MCP보다 더 큰 변화일 수 있다”고 평가했는데요, 실제로 OpenAI가 두 달 만에 이 패턴을 채택한 걸 보면 그 판단이 맞았던 것 같습니다. MCP는 복잡한 프로토콜 스펙(hosts, clients, servers, transports 등)을 요구하지만, Skills는 “마크다운에 YAML 메타데이터 몇 줄”이 전부니까요.

API에서 Skills 사용하기

OpenAI API의 Shell Tool과 통합되어 두 가지 방식으로 사용할 수 있습니다:

1) Upload 방식: POST /v1/skills로 skill을 먼저 업로드하고, skill_id로 참조합니다. 업로드는 zip 파일이나 개별 파일 모두 가능하고요.

2) Inline 방식: API 요청에 base64로 인코딩한 zip 파일을 직접 포함시킵니다. 별도 업로드 없이 바로 사용할 수 있어서 더 간편하죠.

Shell 환경도 두 가지입니다. Hosted Shell(container_auto)은 OpenAI가 제공하는 샌드박스 환경이고, Local Shell은 로컬 머신에서 직접 실행하는 방식입니다. 어느 쪽이든 skill 선택과 프롬프트 동작은 동일하게 작동합니다.

OpenAI만의 차별점

Skills는 Anthropic이 만든 오픈 스탠다드이고, OpenAI가 이를 채택했습니다. 차별점은 어디서 사용하느냐입니다.

Anthropic의 Skills가 Claude Desktop이나 웹 인터페이스 내에서 작동한다면, OpenAI는 이 개념을 API 레벨로 가져왔습니다. Shell Tool과 통합되어 프로그래밍 방식으로 호출할 수 있고, hosted와 local 환경 모두를 지원하며, 버전 관리(default_version, latest_version)도 명시적으로 제공하죠.

특히 inline base64 방식은 편의성을 더합니다. 별도 업로드 없이 API 요청에 base64로 인코딩한 zip 파일을 직접 포함시킬 수 있어서, 간단한 테스트나 일회성 작업에 유용합니다.

두 접근 모두 “파일시스템 접근 + 코드 실행 환경”이 필수라는 공통점이 있습니다. 그래서 ChatGPT Code Interpreter나 Claude Code 같은 환경에서 빛을 발하는 거죠.

실무 활용 포인트

OpenAI 문서는 몇 가지 베스트 프랙티스를 강조합니다. 먼저 Skills를 “작은 CLI처럼 설계하라”는 것. 커맨드라인에서 실행 가능하고, 명확한 출력을 내고, 실패 시 명확한 에러를 보여줘야 합니다.

버전 관리도 중요합니다. 프로덕션에서는 “최신 버전”이 아닌 특정 버전을 고정해서 사용해야 예측 가능한 동작을 보장할 수 있죠. 모델 버전과 skill 버전을 함께 고정하면 재현 가능한 배포가 됩니다.

그리고 시스템 프롬프트에 절차를 중복해서 넣지 말라고 합니다. 전체 절차를 프롬프트에 반복하면 Skills의 핵심 가치(재사용성, 버전 관리, 조건부 호출)를 잃게 되니까요.

공식 문서에는 CSV 분석 skill을 만드는 runnable example도 포함되어 있습니다. SKILL.md, Python 스크립트, requirements.txt를 묶어서 zip으로 업로드하는 전체 과정을 보여주죠.

참고자료:

• Skills | OpenAI API – OpenAI Developer Documentation
• Skills in OpenAI API – Simon Willison
• Claude Skills are awesome, maybe a bigger deal than MCP – Simon Willison
• OpenAI are quietly adopting skills – Simon Willison