Codex 사용자 정의 프롬프트를 전체 저장소에서 사용할 수 있는 스킬로 변환하는 방법 (2026년 가이드)

이전 포맷에 대한 OpenAI의 페이지는 다음과 같은 판정으로 시작합니다: "사용자 정의 프롬프트는 지원 중단되었습니다. Codex가 명시적 또는 암시적으로 호출할 수 있는 재사용 가능한 지침에는 스킬을 사용하세요."

동일한 페이지에서 이러한 변화가 필요했던 한계를 설명합니다. "사용자 정의 프롬프트는 명시적인 호출이 필요하며 로컬 Codex 홈 디렉터리(예: ~/.codex)에 저장되므로 저장소를 통해 공유되지 않습니다. 프롬프트를 공유하고 싶거나(또는 Codex가 암시적으로 호출하도록 하려면) 스킬을 사용하세요."

이 문장이 모든 것을 말해줍니다. 사용자 정의 프롬프트는 구조상 개인용입니다. ~/.codex/prompts에 저장되고, 이름을 입력하여 호출되며, 동일한 저장소를 클론하는 동료는 이를 전혀 사용할 수 없습니다. 프롬프트에 담긴 프로세스 지식이 무엇이든 간에, 실제로는 한 사람만의 지식으로 남게 됩니다.

스킬은 그 반대를 위해 만들어졌습니다. OpenAI는 스킬을 "어느 제품이든 워크플로우를 안정적으로 따를 수 있도록 지침, 리소스 및 선택적 스크립트를 패키징하는 것"으로 설명하며, Codex는 여러 위치에서 이를 읽어옵니다. 저장소의 경우, "Codex는 현재 작업 디렉터리부터 저장소 루트까지 모든 디렉터리의 .agents/skills를 스캔합니다." 사용자, 관리자, 시스템 위치도 존재하지만, 스킬을 공유 가능하게 만드는 것은 바로 저장소 위치입니다.

폴더 이름에 주의하세요. .codex 내부의 폴더가 아니라 .agents/skills입니다. 사용자 수준의 위치도 동일한 패턴을 따릅니다: $HOME/.agents/skills. Codex 홈 디렉터리 내부에서 Codex 스킬 폴더를 찾는 사람들은 잘못된 곳을 찾고 있는 것입니다.

스킬은 Codex CLI 외에서도 작동합니다. "독립형 스킬은 ChatGPT 데스크톱 앱, Codex CLI 및 IDE 확장 프로그램에서 사용할 수 있습니다." 이러한 광범위한 호환성이 이전 포맷을 유지하는 대신 폐지하는 이유 중 하나입니다.

프롬프트를 그대로 두기. 현재로서는 계속 작동하지만, 지원 중단되었다는 것은 새로운 기능이 적용되지 않음을 의미하며, 팀의 다른 누구에게도 보이지 않는 상태로 남게 됩니다.

각 프롬프트를 변경 없이 SKILL.md에 붙여넣기. 결과는 그럴듯해 보이지만 다르게 작동합니다. 프롬프트는 이름을 입력했을 때만 실행되었습니다. 반면 스킬은 자동으로 선택될 수 있습니다: Codex는 "암시적 호출(Implicit invocation)"을 통해 "작업이 스킬의 description(설명)과 일치할 때" 스킬을 활성화할 수 있습니다. 사용자의 명령을 기다리던 배포 루틴이 이제 스스로 실행을 제안할 수 있습니다.

플레이스홀더를 그대로 유지하고 여전히 확장되기를 바라기. 사용자 정의 프롬프트는 "명령어 뒤에 공백으로 구분하여 제공하는 인자로부터 확장되는" 1부터 9까지의 위치 플레이스홀더와 $ARGUMENTS, 그리고 $FILE과 같은 명명된 플레이스홀더를 지원합니다. 스킬 문서에는 이와 동등한 플레이스홀더 확장에 대한 설명이 없습니다. OpenAI의 가져오기(import) 가이드는 바로 이 범주를 검토 대상으로 지정하고 있습니다: "인자, 셸 보간(shell interpolation) 또는 파일 경로 플레이스홀더에 의존하는 프롬프트 템플릿 또는 명령형 프롬프트."

모든 스킬을 저장소 루트에 두기. Codex가 계층 구조를 제공하는 데는 이유가 있습니다. 특정 서비스에만 관련된 스킬은 해당 서비스의 디렉터리에 둘 수 있으며, 루트 수준의 스킬은 모든 하위 폴더에서 보입니다.

가져오기 도구(importer)에만 의존하기. OpenAI의 가져오기 흐름은 다른 에이전트에서 설정을 가져올 때 "슬래시 명령어(Slash commands)"를 "스킬(Skills)"로 매핑하며, 이는 다른 도구의 명령어를 처리합니다. 이는 시작점일 뿐이며, 철저한 검토를 대신할 수 없습니다.

목표는 기존 프롬프트가 하던 일을 수행하고, 팀이 볼 수 있는 곳에 위치하며, 원하는 때에만 트리거되는 스킬 세트를 구축하는 것입니다.

1단계: 프롬프트 인벤토리 작성 및 대상별 분류

~/.codex/prompts를 열고 모든 파일을 나열합니다. 각 파일에 대해 세 가지 사항을 기록하세요: 수행하는 작업, 인자(arguments) 수신 여부, 개인용 프로세스인지 팀 프로세스인지 여부입니다.

선호하는 커밋 메시지 스타일이나 개인적인 습관과 같은 개인용 프롬프트는 $HOME/.agents/skills와 같은 사용자 수준에 속합니다. 이 위치에 대해 OpenAI가 제안하는 용도는 "사용자가 작업하는 모든 저장소에 적용되는, 사용자에게 유용한 스킬을 관리하는 것"입니다.

저장소에서 릴리스를 배포하는 방법, 리뷰를 진행하는 방법과 같은 팀 프로세스는 저장소에 속해야 합니다. 저장소의 모든 곳에 적용된다면 루트를 사용하세요. OpenAI는 루트 스킬을 "저장소의 모든 하위 폴더에서 사용 가능"하다고 설명합니다. 특정 영역에만 적용된다면 더 가까운 곳에 두세요. 폴더 수준의 스킬은 "마이크로서비스 또는 모듈에만 관련된 스킬"에 적합합니다.

목록을 작성하는 동안 목적이 중복되는 프롬프트가 있는지 확인하세요. Codex는 중복을 조정하지 않습니다: "두 스킬이 동일한 name을 공유하는 경우, Codex는 이를 병합하지 않으며 둘 다 스킬 선택기에 나타날 수 있습니다." 이름이 같은 거의 동일한 두 스킬이 모두 표시되면 사용자 자신과 팀원들에게 혼란을 줄 수 있습니다.

2단계: 각 프롬프트를 스킬로 재작성하고 플레이스홀더를 명시적 입력으로 대체

스킬은 SKILL.md 파일이 포함된 폴더이며, "SKILL.md 파일에는 반드시 name과 description이 포함되어야 합니다." 프롬프트당 하나의 폴더를 생성하세요.

설명(description)은 작성할 가장 중요한 줄입니다. Codex가 스킬 적용 여부를 결정하는 기준이 되기 때문입니다. OpenAI의 가이드라인은 다음과 같습니다: "명확한 범위와 경계를 가진 간결한 설명을 작성하세요. 설명이 단축되더라도 호스트가 스킬을 매칭할 수 있도록 핵심 사용 사례와 트리거 단어를 앞부분에 배치하세요." 크리에이터 템플릿은 이를 더욱 명확하게 표현합니다: "이 스킬이 언제 트리거되어야 하고 언제 트리거되지 않아야 하는지 정확히 설명하세요."

인자를 받던 프롬프트의 경우, 각 플레이스홀더를 지침에서 요구하는 명시적인 입력으로 변환하세요. 프롬프트가 Codex에 "먼저 스테이징하세요: $FILES"라고 지시했던 부분을, 스킬에서는 어떤 파일을 스테이징해야 하는지, 그리고 지시받지 않았을 때 어떻게 확인해야 하는지 명시합니다. 스킬에 대한 OpenAI의 모범 사례도 동일한 방향을 제시합니다: "명시적인 입력과 출력을 가진 명령형 단계로 작성하세요."

각 스킬이 하나의 작업에만 집중하도록 하세요. OpenAI는 모범 사례 중 첫 번째로 "각 스킬이 하나의 작업에 집중하도록 유지할 것"을 꼽았습니다. 또한 "결정론적 동작이나 외부 도구가 필요한 경우가 아니라면" 스크립트보다 지침(instructions)을 우선적으로 사용하세요.

프롬프트를 설명하는 것보다 직접 보여주는 것이 더 쉽다면, OpenAI는 두 가지 다른 경로를 제공합니다. Codex에서 $skill-creator로 호출되는 내장 크리에이터는 "스킬이 무엇을 하는지, 언제 트리거되어야 하는지, 지침 전용으로 유지할지 아니면 스크립트를 포함할지 묻습니다." 다른 하나는 시연을 통해 스킬 초안을 작성하는 Record & Replay 기능입니다.

3단계: 호출 방식 결정, 중복 비활성화 및 트리거 테스트

변환된 모든 스킬에 대해 스스로 실행되도록 허용할지 여부를 결정하세요. 배포, 풀 리퀘스트 생성, 브랜치 삭제 등 부작용(side effects)이 있는 작업은 명시적 호출로 유지하는 것이 좋습니다.

OpenAI는 스킬 내부의 선택 사항인 agents/openai.yaml 파일에서 이에 대한 스위치를 제공합니다. allow_implicit_invocation은 기본적으로 true로 설정되며, "false로 설정하면 Codex는 사용자 프롬프트를 기반으로 스킬을 암시적으로 호출하지 않으며, 명시적인 $skill 호출은 여전히 작동합니다." 이를 통해 필요한 스킬에 대해 이전 프롬프트의 동작을 복원할 수 있습니다.

스킬을 삭제하지 않고 폐기하려면, OpenAI 문서에 따라 ~/.codex/config.toml에 enabled = false가 포함된 [[skills.config]] 항목을 추가한 후 재시작하면 됩니다.

그런 다음 테스트를 진행합니다. OpenAI는 "올바른 트리거 동작을 확인하기 위해 스킬 설명에 대해 프롬프트를 테스트할 것"을 권장합니다. Codex에 각 스킬을 트리거해야 하는 몇 가지 작업과 트리거하지 않아야 하는 몇 가지 작업을 제공하고, 결과가 의도와 일치할 때까지 설명을 조정하세요. Codex는 "스킬 변경 사항을 자동으로 감지"하며, 업데이트가 반영되지 않으면 재시작을 제안합니다.

마지막으로 스킬이 올바르게 작동하면, 각 루틴의 단일 버전만 남도록 이전 프롬프트 파일을 제거합니다.

변환된 스킬은 작업을 수행하는 방법을 캡처합니다. 하지만 작업이 왜 그런 방식으로 수행되는지(예: 릴리스 체크리스트를 만들게 된 장애 사건, 리뷰 시 마이그레이션을 먼저 확인해야 하는 이유 등)인 이유는 캡처하지 못합니다. MemoryLake는 이러한 이유들을 보관하는 공간으로, 절차와 그 근거가 서로 어긋나지 않도록 도와줍니다.

여러분은 자신만의 언어로 직접 항목을 작성합니다. Codex 홈 폴더, 저장소의 스킬 디렉터리 또는 다른 벤더의 저장소에서 데이터를 읽거나 쓰거나 삭제하지 않습니다.

1단계: API 키 생성

로그인 후 대시보드에서 키를 생성합니다. 이 키를 통해 에이전트는 Codex나 팀이 사용하는 다른 도구에서 여러분이 작성한 항목을 읽을 수 있습니다.

2단계: 첫 번째 메모리 업로드

각 팀 스킬에 대해 그 이면의 결정을 추가하세요. 해당 단계가 존재하는 이유, 그것이 없었을 때 발생했던 문제, 그리고 누가 이에 동의했는지 등을 기록합니다. 항목당 하나의 결정을 이유와 함께 첨부합니다.

3단계: AI 및 에이전트 연결

에이전트가 워크스페이스를 가리키도록 설정합니다. 그러면 .agents/skills를 전혀 읽지 않는 도구를 포함하여 작업이 일어나는 모든 곳에서 그 근거를 활용할 수 있게 됩니다.

첫 번째 차이점은 프로세스 지식이 팀의 지식이 된다는 것입니다. 한 사람의 홈 폴더에 있는 프롬프트는 그 사람이 떠나면 함께 사라집니다. 저장소에 있는 스킬은 리뷰되고 버전 관리되며 모두가 사용할 수 있습니다. 이는 Codex가 AGENTS.md 규칙을 일관되게 따르도록 만드는 것을 개인의 문제가 아닌 팀의 관심사로 전환하는 것과 동일한 변화입니다.

두 번째는 호출이 하나의 결정 사항이 된다는 점입니다. 프롬프트는 항상 명시적이었습니다. 스킬은 기본적으로 자동 사용 대상이 됩니다. 스킬별로 이 선택을 조정하는 약간의 작업만으로도 큰 혼란을 방지할 수 있습니다.

세 번째는 규칙(rules)과 절차(procedures)의 구분이 더 명확해진다는 점입니다. 항상 참인 프로젝트 사실은 지침 파일에 속하고, 작업 절차는 스킬에 속합니다. Cursor에 대해 스킬과 규칙을 언제 사용해야 하는지에서 논의된 것과 동일한 구분이 여기에도 똑같이 적용됩니다. 이 둘을 혼용하는 것이 애초에 Codex가 프로젝트 컨텍스트를 잊어버리는 이유 중 하나입니다.

네 번째는 이식성(portability)입니다. 스킬은 개방형 표준을 따르므로 동일한 폴더가 여러 도구에서 유용하게 사용될 수 있습니다. 이는 Devin 메모리를 스킬로 이동하는 것의 배경이 되는 패턴이자, Zed의 스킬 카탈로그처럼 예상치 못한 카탈로그에 스킬이 등장하는 배경이기도 합니다.

.codex가 아닌 .agents/skills를 확인하세요. 저장소 스킬은 .agents/skills 디렉터리에 위치하며, 사용자 스킬은 $HOME/.agents/skills에 위치합니다.

변환하기 전에 개인용과 팀용을 분류하세요. 스킬이 저장되는 위치에 따라 누가 이를 사용할 수 있는지가 결정됩니다.

설명(description)을 트리거 조건으로 작성하세요. 언제 적용되어야 하고 언제 적용되지 않아야 하는지 명시하고, 핵심 단어를 앞부분에 배치하세요.

플레이스홀더를 명시적 입력으로 대체하세요. 스킬 문서에는 인자 확장에 대한 설명이 없으며, OpenAI의 가져오기 가이드는 플레이스홀더에 의존하는 프롬프트를 검토 대상으로 지정하고 있습니다.

부작용이 있는 작업에 대해서는 암시적 호출을 끄세요. allow_implicit_invocation을 false로 설정하여 해당 스킬들을 명시적 호출 상태로 유지하세요.

각 스킬에 고유한 이름을 부여하세요. Codex는 이름이 같은 스킬을 병합하지 않고 나란히 표시합니다.

근거를 영구적인 곳에 보관하세요. 스킬은 절차이지 메모리가 아닙니다. Grok의 스킬이 AI 메모리에 의미하는 바에서도 다른 벤더에 대해 동일한 구분을 적용하고 있으며, Cursor 규칙을 Codex로 마이그레이션하기에서는 항상 켜져 있는 지침을 이동하는 인접한 작업을 다룹니다.

OpenAI의 지원 중단 공지는 두 문장으로 구성되어 있으며, 두 번째 문장이 모든 것을 설명합니다. 사용자 정의 프롬프트는 "로컬 Codex 홈 디렉터리에 저장"되므로 "저장소를 통해 공유되지 않습니다." 스킬은 이 문제를 해결합니다. 스킬은 .agents/skills에 저장되며, 폴더 또는 전체 저장소로 범위를 지정할 수 있고, Codex CLI, IDE 확장 프로그램, ChatGPT 데스크톱 앱 전반에서 작동합니다.

변환 과정에서 주의가 필요합니다. 별도로 설정하지 않으면 스킬이 스스로 트리거될 수 있으며, 기존 프롬프트가 의존하던 플레이스홀더는 명시적인 입력으로 변환되어야 합니다.

프롬프트 인벤토리를 작성하고, 대상별로 분류하고, 각각 정확한 설명과 함께 재작성하고, 호출 방식을 신중하게 설정한 후 트리거를 테스트하세요. 그런 다음 이전 파일을 삭제하고, 다음 팀원이 읽을 수 있도록 각 루틴의 이면에 있는 이유를 어딘가에 보관해 두세요.