Xcode 27을 활동 도구 체인으로 선택한 뒤 Apple이 안내한 방식으로 Agent Skills를 Codex의 스킬 디렉터리에 내보내세요. 내보내기 명령의 성공만으로 Codex가 스킬을 읽었다고 판단하지 말고, 경로와 실제 Swift 작업까지 확인해야 합니다.
- Codex로 Swift 또는 SwiftUI 프로젝트를 개발하며 Apple이 제공한 안내를 활용하려는 개발자에게 적합합니다.
- SSH로 원격 Mac을 관리하고 여러 Xcode 도구 체인을 유지하는 DevOps 엔지니어도 따라 할 수 있습니다.
- 팀 저장소의 공유 지침과 개인 계정 스킬 디렉터리를 분리하려는 플랫폼 담당자에게도 유용합니다.
마지막 업데이트: 2026년 10월 10일. Xcode 27의 알려진 문제와 처리 방법은 Apple의 Xcode 27 출시 노트, 도구 체인 관련 조건은 Apple의 Xcode 시스템 요구 사항과 명령줄 도구 안내를 기준으로 확인하세요. Codex의 스킬 발견 위치는 OpenAI의 스킬 안내도 함께 확인해야 합니다.
SECTION 01 Xcode 27 Agent Skills가 Codex에 없는 원인은 무엇인가요?
대표적인 원인은 세 가지입니다. xcrun이 Xcode 27이 아닌 다른 개발자 디렉터리를 참조하거나, 내보내기 대상이 Codex가 확인하는 위치와 다르거나, 파일은 만들어졌지만 Codex가 아직 해당 경로를 읽지 못한 경우입니다. Apple은 Xcode 27 출시 노트에서 Apple이 작성한 Agent Skills가 Codex에 나타나지 않을 수 있는 문제와 처리 방법을 안내합니다. 해당 출시 노트의 지침에 따라 도구 체인을 먼저 맞춘 뒤 내보내세요.
| 확인 결과 | 의미 | 다음 조치 |
|---|---|---|
xcrun 명령을 찾을 수 없음 |
선택한 개발자 디렉터리에 필요한 도구가 없을 수 있습니다. | 활동 도구 체인을 확인하고 Xcode 27을 선택합니다. |
| 내보내기 명령은 성공했지만 대상 폴더가 비어 있음 | 내보내기가 완료된 위치가 예상과 다를 수 있습니다. | 명령의 대상 경로와 실제 폴더 내용을 대조합니다. |
| 스킬 파일은 있으나 Codex가 따르지 않음 | 파일 생성과 Codex의 발견·사용은 별도 상태입니다. | Codex가 읽는 경로인지 확인하고 실제 작업으로 검증합니다. |
여기서 중요한 구분은 파일을 내보냈다와 Codex가 파일을 읽어 작업에 적용했다가 같은 결과가 아니라는 점입니다. Apple의 개발자 세션에서는 Agent Skills 내보내기 흐름을 설명하지만, 사용 중인 Codex 버전이 해당 파일을 실제로 발견하고 적용하는지는 별도로 확인해야 합니다. Apple 개발자 세션의 내보내기 설명을 참고하되, 최종 판단은 현재 설치된 Codex에서 내리세요.
SECTION 02
첫 번째 점검: xcrun은 실제로 Xcode 27을 사용하나요?
터미널에서 xcrun이 실행된다는 사실만으로는 충분하지 않습니다. 먼저 현재 선택된 개발자 디렉터리와 Xcode 버전을 출력해, 명령이 어느 설치본에 연결되어 있는지 확인하세요. Apple은 개발자 도구 선택과 명령줄 도구를 별도로 설명하므로, Xcode가 여러 개 설치된 환경에서는 경로 자체가 진단 근거가 됩니다. Apple의 명령줄 도구 설명과 명령줄 도구 기술 노트를 참고하세요.
xcode-select -p
xcodebuild -version
xcrun --find swift
xcode-select -p가 출력한 경로가 의도한 Xcode 27 설치본의 Contents/Developer인지 확인합니다. 앱 이름이나 설치 위치는 시스템마다 다를 수 있으므로, 아래 경로의 앱 이름은 실제 위치에 맞게 바꾸세요.
sudo xcode-select --switch "/Applications/Xcode-27.app/Contents/Developer"
그다음 위의 확인 명령을 다시 실행합니다. 버전 출력이 Xcode 27을 가리키지 않거나 xcrun이 다른 설치본 아래의 도구를 찾는다면 아직 내보내기를 진행하지 마세요. Apple의 Xcode 시스템 요구 사항도 사용 중인 macOS와 Xcode 조합이 지원되는지 판단할 때 확인할 자료입니다.
SECTION 03
두 번째 점검: xcrun agent skills export는 Codex 경로에 기록했나요?
활동 도구 체인을 확인한 다음, Apple의 Xcode 27 출시 노트에 안내된 Codex 내보내기 절차를 그대로 따르세요. 명령 이름은 다음과 같이 확인할 수 있습니다.
xcrun agent skills export
실제 인수나 대상 선택 방식은 설치된 Xcode의 안내와 Apple 출시 노트에 표시된 절차를 기준으로 하세요. 확인하지 않은 옵션을 덧붙이지 마세요. 내보내기가 끝나면 터미널의 완료 메시지만 믿지 말고, 안내된 대상 경로에 스킬 파일이 만들어졌는지 파일 목록으로 확인합니다. Codex의 스킬 안내에서 개인 계정 또는 프로젝트에 적용되는 검색 위치를 확인하고, 내보낸 위치와 맞는지 비교하세요. Codex 스킬 안내는 스킬의 구조와 발견 경로를 확인하는 기준입니다.
이 단계에서 경로가 일치하지 않으면 내보내기를 반복하기보다 대상부터 바로잡으세요. 특히 원격 Mac에서 SSH로 접속한 계정과 Codex를 실행하는 계정이 다르면, 홈 디렉터리도 달라질 수 있습니다. ~가 어느 계정의 홈을 가리키는지 확인하지 않은 채 경로를 복사하면 다른 위치에 파일이 생길 수 있습니다.
원격 터미널에서 확인한 파일은 Codex를 실행하는 계정의 파일인지도 확인하세요. 내보내기 대상, 로그인 계정, Codex 실행 계정 중 하나라도 다르면 파일이 존재해도 스킬을 찾지 못할 수 있습니다.
개인 경로와 팀 공유 경로는 따로 판단하세요
| 배치 위치 | 적합한 용도 | 확인할 점 |
|---|---|---|
| Codex의 개인 스킬 디렉터리 | 개인 개발 환경에서 반복해 쓸 안내 | 내보낸 계정과 Codex 실행 계정이 같은지 확인합니다. |
| 프로젝트의 스킬 디렉터리 | 저장소에서 팀과 함께 관리할 안내 | 버전 관리 대상과 구성원별 적용 범위를 검토합니다. |
개인 디렉터리는 한 개발자의 환경에 맞는 설정을 두기에 알맞고, 프로젝트 디렉터리는 저장소를 받는 팀원이 함께 확인할 지침을 관리하는 데 적합합니다. 두 위치를 혼용하면 팀원이 같은 저장소를 사용해도 서로 다른 결과를 얻을 수 있습니다. 기존 파일을 덮어쓸 수 있는 옵션이 Apple의 현재 문서에 명시되어 있다면 그 옵션의 동작을 먼저 확인하고, 되돌릴 복사본을 확보한 뒤 사용하세요. 문서에서 확인하지 못한 덮어쓰기 동작은 추정하지 마세요.
SECTION 04 세 번째 점검: 파일은 있지만 Codex가 읽지 않는다면 무엇을 확인하나요?
다음 항목을 순서대로 대조하세요. 이는 Codex가 항상 특정 파일을 자동으로 적용한다고 가정하지 않기 위한 확인 과정입니다.
xcode-select -p출력이 의도한 Xcode 27의 개발자 디렉터리인지 확인합니다.xcodebuild -version과xcrun --find swift출력이 같은 도구 체인에 속하는지 확인합니다.- Apple이 안내한 Codex 내보내기 대상과 실제 스킬 파일의 위치를 대조합니다.
- 파일이 개인 계정 경로에 있는지 프로젝트 경로에 있는지 기록하고, Codex 실행 계정과 일치하는지 확인합니다.
- 현재 Codex 버전의 스킬 안내에서 해당 위치의 발견 규칙과 재검색 방법을 확인합니다.
- 한 가지 원인을 수정한 뒤에만 다시 확인합니다. 원인을 분리하지 않은 채 경로나 파일을 계속 덮어쓰지 마세요.
Codex의 스킬 발견 방식이나 재검색 시점은 버전과 설정에 따라 달라질 수 있으므로, 공식 문서에 없는 동작을 확정된 규칙처럼 취급하지 마세요. 내보낸 파일이 읽히지 않는 상태라면 파일 목록, 활동 도구 체인 출력, Codex 버전과 실행 계정을 함께 기록해야 원인을 좁힐 수 있습니다.
SECTION 05 마지막 단계: 실제 Swift 작업으로 수정 결과를 검증하세요
스킬 파일이 올바른 위치에 있는지 확인했다면, 그 스킬의 범위와 맞는 작은 Swift, SwiftUI 또는 UIKit 작업을 Codex에 요청하세요. 단순히 스킬 파일을 확인했는지만 보지 말고, 작업에 맞는 안내를 읽고 실제 응답이나 변경 결과에 반영했는지 검토합니다.
검증 기록에는 Xcode 버전, xcode-select -p 출력, 내보내기 경로, Codex 버전, 실행 계정, 요청한 작업, 결과를 남기세요. 같은 환경에서 다시 시도할 때 앞선 결과와 비교할 수 있습니다. 기대한 안내가 반영되지 않으면 파일을 다시 덮어쓰기 전에 경로와 Codex의 검색 규칙을 재확인하고, 확인되지 않은 원인을 해결된 것으로 표시하지 마세요.
아직 Xcode 27을 선택할 수 있는 macOS 환경이 없다면 먼저 원격 Mac 접속 환경과 요금 안내를 살펴보고, VPSNIX 서비스 안내에서 사용 가능한 접속 방식을 확인할 수 있습니다. Linux 서버는 macOS 전용 도구 체인을 실행할 수 없고, 개인 Mac은 장시간 켜 두거나 팀과 분리된 테스트 환경으로 운영할 때 전원·가용성·장비 공유 문제가 생길 수 있습니다. 이번 검증처럼 Xcode 도구 체인과 Codex 조합을 확인할 임시 환경이 필요하다면 원격 Mac을 빌려 사용하는 방안이 유연합니다. 반대로 물리 장비 연결이 필요하거나 장기간 같은 Mac에서 지속 부하를 운용해야 한다면 직접 보유하는 편이 더 적합할 수 있습니다.