Codex Skill 설치 방법｜전역·프로젝트 선택과 GitHub 적용 사례

GitHub에서 쓸 만한 Skill을 찾았는데 README에는 .claude/skills만 나온다면 바로 복사하기 어렵습니다.

Codex가 읽는 폴더와 호출 방식이 다르고, 외부 지침이 현재 프로젝트의 AGENTS.md와 충돌할 수도 있기 때문이에요.

이번에는 fire-your-seo-agency 저장소의 v1.1.0을 Codex 프로젝트에 적용했어요. 결론부터 말하면 전역에는 설치하지 않았고, 프로젝트 안의 .agents/skills/fire-your-seo-agency에 검토한 사본을 넣었습니다.

이 사례에서는 프로젝트 설치가 맞았습니다

fire-your-seo-agency는 SEO·AEO·GEO·LLMO·네이버 점검 절차를 묶은 Skill이에요. Sinabro에는 이미 콘텐츠 브리프 승인, 사실 확인, 공개 승인, 색인 측정 순서를 정한 운영 규칙이 있어요.

외부 Skill을 모든 프로젝트에서 자동으로 부르면 이 규칙과 관계없는 작업에도 개입할 수 있어요.

그래서 범위를 먼저 줄였어요. 이 설치본은 Sinabro 프로젝트에서 사용하고, 호출할 때만 동작하며, 기존 AGENTS.md와 글 작성 워크플로를 우선해요.

여러 저장소에 똑같이 적용할 개인 도구가 아니라 프로젝트에 맞게 고친 운영 부품이기 때문이에요.

Codex 앱에서 기존 프로젝트를 수정하고 테스트하는 전체 흐름이 먼저 필요하다면 OpenAI Codex 앱 사용법부터 확인할 수 있어요.

이 글은 그다음 단계인 외부 Skill 설치에 집중합니다.

원본 저장소는 Claude Code용입니다

원본 저장소는 Claude Code용 Skill이에요. README는 Claude 플러그인 명령과 .claude/skills/fire-your-seo-agency 경로를 안내합니다.

반면 OpenAI 공식 문서에서 Codex의 저장소 범위 Skill 경로는 .agents/skills예요.

폴더 안에 SKILL.md와 references가 있다는 공통점만 보고 호환된다고 단정하면 안 됩니다. 배포 메타데이터와 호출 문법, 프로젝트 지침의 우선순위까지 함께 봐야 해요.

2026년 10월 1일 공식 Build skills 문서 기준으로 ChatGPT에서는 @를 입력해 스킬을 선택하고, Codex CLI·IDE 확장에서는 /skills 또는 $로 명시 호출해요. 사용 중인 인터페이스에 맞는 선택 메뉴를 확인하세요.

이 표는 경로를 기계적으로 치환하라는 뜻이 아니에요. 원본은 독립된 외부 프로젝트이고, Codex 적용본은 그 파일을 검토한 뒤 현재 저장소의 목적에 맞게 수정한 사본입니다.

Codex Skill 전역과 프로젝트는 무엇이 다른가요?

Codex Skill의 범위는 누가 몇 개의 작업 폴더에서 사용할지를 기준으로 나눌 수 있어요. OpenAI 공식 문서는 저장소 범위에 .agents/skills, 사용자 범위에 $HOME/.agents/skills를 안내합니다.

판단 질문은 세 개면 충분합니다.

• 다른 프로젝트에서도 같은 지침을 수정 없이 쓸 수 있나요?
• 현재 저장소의 AGENTS.md, 배포 정책이나 콘텐츠 규칙에 의존하나요?
• 잘못 호출됐을 때 영향을 받는 범위를 프로젝트 안으로 제한해야 하나요?

두 번째나 세 번째 질문에 그렇다고 답한다면 프로젝트 설치가 자연스러워요. 반대로 개인 커밋 정리처럼 저장소가 달라도 절차가 같다면 사용자 범위를 검토할 수 있습니다.

외부 Skill은 활성화 전에 먼저 검사합니다

외부 SKILL.md는 설명 문서이면서 에이전트가 따라야 할 작업 절차예요. 파일을 내려받는 것만으로 스크립트가 자동 실행되는 것은 아니지만, Skill이 활성화되면 지침은 이후 행동에 영향을 줘요.

그래서 처음부터 .agents/skills에 복사하기보다 활성 경로 밖의 임시 폴더에서 읽는 편이 안전해요.

먼저 확인할 항목은 다음과 같습니다.

• SKILL.md의 이름, 설명, 호출 범위
• scripts와 외부 명령, 네트워크 요청, 도구 의존성
• 파일 삭제, 전역 설정 변경, 자동 발행처럼 영향이 큰 행동
• 프로젝트 규칙이나 최신 공식 정책과 충돌하는 지침
• 원본 버전과 라이선스, 업데이트 방식
• README의 성과 주장과 실제로 재현할 수 있는 결과의 구분

이 사례에서는 MIT 라이선스와 원본 구조를 확인했습니다. 태그 fire-your-seo-agency--v1.1.0을 커밋 eb9be9fa38cea5c3311b36e0f2d870c0507ff5c1에 고정했어요.

원격 HEAD가 바뀌어도 어떤 내용을 검토했는지 다시 찾을 수 있게 만든 것입니다.

GitHub Skill을 프로젝트용으로 옮긴 실제 순서

1. 임시 폴더에 버전을 고정해 내려받기

아래 명령은 원본을 Codex 활성 경로 밖에 복제합니다. 2026년 8월 28일 같은 태그로 실행해 rev-parse HEAD가 위 커밋을 반환하는 것을 확인했어요.

skill_stage=$(mktemp -d)
git clone --depth 1 --branch fire-your-seo-agency--v1.1.0 \
  https://github.com/leopard627/fire-your-seo-agency.git \
  "$skill_stage/source"
git -C "$skill_stage/source" rev-parse HEAD
find "$skill_stage/source" -maxdepth 2 -type f

태그 이름만 기록하고 끝내지 말고 커밋 값도 남겨야 해요. 태그가 가리키는 실제 파일과 나중에 받은 파일이 같은지 비교하기 쉬워집니다.

2. 검토할 사본에 필요한 파일만 모으기

복제한 폴더에는 원본의 .git과 Claude 배포 메타데이터도 들어 있어요. 이 사례에서는 필요한 콘텐츠만 별도 사본으로 옮기고, 그 사본을 수정했습니다.

mkdir -p "$skill_stage/adapted/agents"
cp "$skill_stage/source/SKILL.md" "$skill_stage/adapted/"
cp "$skill_stage/source/LICENSE" "$skill_stage/adapted/"
cp -R "$skill_stage/source/references" "$skill_stage/adapted/"
cp -R "$skill_stage/source/assets" "$skill_stage/adapted/"

이렇게 하면 활성 Skill 폴더 안에 중첩된 Git 저장소를 만들지 않고, 유지해야 할 MIT 라이선스도 함께 보존할 수 있어요. 원본 README가 업데이트 판단에 필요하다면 검토된 사본에 함께 보관하면 됩니다.

3. Codex 메타데이터와 호출 정책 추가하기

agents/openai.yaml은 Codex 앱의 표시 정보와 호출 정책을 담을 수 있어요. Sinabro 설치본에는 아래처럼 암시 호출을 껐습니다.

interface:
  display_name: "Sinabro SEO Audit"
  short_description: "Sinabro용 SEO·AI 검색 가시성 진단"
  default_prompt: "Sinabro 프로젝트 규칙을 우선해 SEO·색인·AI 검색 가시성을 진단하세요."

policy:
  allow_implicit_invocation: false

allow_implicit_invocation: false는 일반적인 글쓰기 요청과 Skill 설명이 비슷하더라도 자동으로 불리지 않게 하는 장치예요. 필요할 때 이름을 직접 지정해 호출합니다. 이 글의 $fire-your-seo-agency 표기는 Codex CLI·IDE의 호출 예이며, ChatGPT에서는 @ 선택 메뉴를 사용해요.

4. 검토를 마친 사본만 활성 경로로 복사하기

프로젝트 루트에서 앞 단계의 $skill_stage/adapted 사본을 검토하고 SKILL.md와 참고문서 확인을 마친 뒤에만 .agents/skills로 옮겨요. 기존 설치본이 있다면 먼저 비교하고 명령을 멈춰야 합니다.

(
  skill_target=".agents/skills/fire-your-seo-agency"
  if [ -e "$skill_target" ] || [ -L "$skill_target" ]; then
    printf '%s\n' "대상 경로가 이미 있어 중단합니다: $skill_target" >&2
    exit 1
  fi
  if [ ! -f "$skill_stage/adapted/SKILL.md" ]; then
    printf '%s\n' "검토한 사본에 SKILL.md가 없어 중단합니다: $skill_stage/adapted/SKILL.md" >&2
    exit 1
  fi
  mkdir -p .agents/skills &&
    cp -R "$skill_stage/adapted" "$skill_target" &&
    find "$skill_target" -maxdepth 2 -type f
)

대상 경로가 디렉터리·파일·심볼릭 링크(끊어진 링크 포함)로 이미 있으면 먼저 중단해요. 기존 적용본과 새 사본을 비교한 뒤 교체 여부를 따로 결정해야 합니다. 검토 사본에 SKILL.md가 없거나 mkdir, cp가 실패해도 뒤의 find는 실행되지 않아야 해요.

검증 메모(2026년 9월 9일): Bash와 zsh의 임시 폴더에서 새 대상·기존 경로·필수 파일 누락·명령 실패를 확인했어요. 괄호 ( ) 안의 exit는 하위 셸을 종료해요. 상위 셸의 오류 종료 옵션에 따라 이후 실행은 달라질 수 있어요.

Codex는 Skill 변경을 자동으로 감지하지만 목록에 보이지 않으면 앱이나 세션을 다시 시작해 확인할 수 있어요.

원본을 그대로 복사하지 않은 이유

원본이 나쁘다는 뜻은 아니에요. 범용 Skill의 기본값과 현재 프로젝트의 운영 기준이 달랐습니다. Sinabro는 이미 Google 공식 정책, 기존 글 충돌 검사, 공개 승인과 색인 측정 일정을 별도로 관리하고 있어요.

실제 수정한 경계는 네 가지입니다.

• 프로젝트 AGENTS.md와 26단계 글 작성 워크플로를 외부 Skill보다 먼저 적용했어요.
• 검증되지 않은 안내 파일을 Google이나 ChatGPT 노출의 즉시 개선 수단으로 배포하지 않게 했어요.
• Google 노출을 목적으로 새로운 FAQ 구조화 데이터를 만들지 않게 했어요.
• 같은 답을 요구하는 검색어 표현을 여러 페이지로 나누지 않고 기존 글과 검색 의도를 먼저 비교하게 했어요.

프로젝트 지침을 어디에 두고 어떤 파일이 우선하는지는 Codex AGENTS.md 작성법에서 더 자세히 확인할 수 있어요.

Skill은 특정 작업 절차이고, AGENTS.md는 해당 저장소에서 계속 지켜야 할 운영 계약이라는 차이가 있어요.

설치가 끝났는지 RED/GREEN으로 확인합니다

Skill 이름이 목록에 보인다고 정책까지 맞게 동작하는 것은 아니에요. 이 사례에서는 원본이 프로젝트 규칙과 충돌하는 요청을 먼저 통과시키는지 확인하고, 수정본이 같은 요청을 막는지 비교했습니다.

반례는 Skill이 해서는 안 되는 일을 구체적으로 드러내야 해요. 설치됐나요?처럼 성공 경로만 묻는 테스트로는 과도한 자동 발행, 중복 페이지 생성이나 오래된 정책 적용을 잡기 어렵습니다.

마지막으로 실제 호출 결과에 다음 네 가지가 남는지 봅니다.

• 프로젝트 규칙을 먼저 읽는가?
• 진단과 구현을 구분하고 승인 경계를 지키는가?
• 확인하지 않은 성과를 만들지 않는가?
• 수정 뒤 언제 무엇을 측정할지 남기는가?

업데이트할 때는 원본을 덮어쓰지 않습니다

로컬 적용본은 원본과 달라졌기 때문에 git pull이나 새 clone 결과로 바로 덮어쓰면 가드레일이 사라질 수 있어요. 업데이트도 설치와 같은 순서로 처리합니다.

1. 새 태그를 별도 임시 폴더에 받습니다.
2. 이전에 고정한 커밋과 새 태그의 SKILL.md, 참고문서를 비교합니다.
3. 프로젝트 우선 규칙이 필요한 부분을 다시 적용합니다.
4. 기존 RED/GREEN 요청을 새 사본에 반복합니다.
5. 통과한 사본만 프로젝트 활성 경로와 교체합니다.
6. 변경일, 원본 버전과 검증 결과를 적용 기록에 남깁니다.

자동 업데이트가 항상 좋은 것은 아니에요. 원본의 개선도 가져와야 하지만, 현재 프로젝트가 의존하는 예외와 공개 승인 경계가 지워지지 않았는지 함께 확인해야 합니다.

외부 Codex Skill 설치 전 체크리스트

설치 완료는 파일 복사가 아니라 범위·출처·행동 경계를 설명할 수 있는 상태예요. 활성화 전에 아래 항목을 한 번 확인합니다.

• 원본 저장소와 작성자를 확인했나요?
• SKILL.md, 참고문서, 스크립트와 도구 의존성을 읽었나요?
• 라이선스와 고정한 태그·커밋을 기록했나요?
• 프로젝트와 사용자 범위 중 하나를 근거와 함께 선택했나요?
• 프로젝트 AGENTS.md와 충돌하는 지침을 찾았나요?
• 삭제, 전역 변경, 외부 발행과 인증정보 접근을 검사했나요?
• 암시 호출이 필요한지 결정했나요?
• 성공 경로뿐 아니라 거절해야 할 요청도 테스트했나요?
• 업데이트 때 덮어쓰지 않을 비교 절차를 남겼나요?

여기까지 확인해야 설치가 파일 복사에서 운영 가능한 도구로 바뀝니다. 검색 성과나 생산성 변화는 설치 직후 주장할 수 없고, 실제 작업과 측정 결과가 쌓인 뒤 따로 판단해야 해요.

자주 묻는 질문 (FAQ)

.codex/skills와 .agents/skills 중 어디에 설치해야 하나요?

직접 관리하는 프로젝트 Skill이라면 OpenAI 공식 문서가 안내하는 .agents/skills를 기준으로 봐요.

내장 설치 도구가 관리하는 위치와 수동 작성 위치는 다를 수 있어요. 임의의 폴더를 추측하기보다 현재 Codex 문서와 설치 도구의 안내를 함께 확인하세요.

Skill 폴더를 추가했는데 목록에 보이지 않으면 어떻게 하나요?

먼저 폴더 바로 아래에 SKILL.md가 있는지 확인하세요. frontmatter의 name과 description, 현재 작업 폴더에서 저장소 루트까지의 .agents/skills 경로도 함께 봐야 해요.

파일이 정상인데도 보이지 않으면 Codex 앱이나 세션을 다시 시작해 확인할 수 있어요.

프로젝트와 사용자 폴더에 같은 이름의 Skill이 있으면 어떤 것을 고르나요?

공식 문서에 따르면 같은 name의 Skill은 하나로 합쳐지지 않고 둘 다 선택 목록에 나타날 수 있어요. 프로젝트 사본과 사용자 사본이 함께 있다면 이름만 보고 우선순위를 가정하지 마세요. 선택 항목의 경로와 실제로 읽은 SKILL.md 경로가 프로젝트의 .agents/skills인지 사용자 $HOME/.agents/skills인지 확인한 뒤 진행하세요.

GitHub Skill을 업데이트할 때 다시 clone하면 되나요?

새 버전은 별도 폴더에 clone해 비교하는 편이 맞아요. 프로젝트 적용본을 바로 덮어쓰면 로컬 가드레일과 agents/openai.yaml이 사라질 수 있으므로, 차이 검토와 RED/GREEN 테스트 뒤에 교체해야 합니다.

공식 출처와 확인일

Codex의 저장 위치와 호출 방식은 OpenAI Build skills 문서에서 확인했어요.

설치 사례에 사용한 파일은 fire-your-seo-agency GitHub 저장소의 고정 태그를 기준으로 삼았습니다.

설치 사례의 원본 상태는 2026년 8월 28일에 확인했어요. 2026년 9월 9일 설치 명령 검증 기록도 그대로 유지했어요.

공식 스킬 문서는 2026년 10월 1일 다시 확인했고, 기존 developers.openai.com/codex/skills 주소가 learn.chatgpt.com/docs/build-skills로 이동하는 것을 확인했어요. 이번 보완은 호출 방식과 동명 Skill 선택 안내이며 새 설치·호출 시험을 했다는 뜻은 아니에요.

지금 할 일

먼저 설치하려는 저장소를 활성 경로 밖에 내려받고 SKILL.md, 스크립트, 라이선스와 버전을 확인하세요.

프로젝트 전용 판단이 섰다면 검토한 사본만 .agents/skills에 넣어요. 그다음 Skill이 반드시 거절해야 할 요청 하나를 정해 테스트합니다.