Codex Skill 등록하기 - bcpprm 사례로 익히는 워크플로 자동화 가이드

개발을 하다 보면 반복해서 수행하는 작업이 생깁니다. 변경 사항을 확인하고, 브랜치를 만들고, 커밋 메시지를 정리한 뒤, 원격 저장소에 푸시하고 PR까지 생성하는 흐름도 그중 하나입니다.

 

이런 반복 작업을 매번 자연어로 길게 설명하는 대신, Codex가 일정한 규칙에 따라 수행하도록 만들 수 있는 방법이 Skill입니다.

이 글에서는 제가 실제로 등록한 bcpprm Skill을 사례로 삼아, Codex에 새로운 Skill을 등록하는 전체 과정을 정리합니다. 이후 다른 자동화 Skill을 만들 때에도 그대로 참고할 수 있도록 기록합니다.

예시로 사용하는 bcpprm는 Branch → Commit → Push → Pull Request 흐름을 지원하도록 만든 Skill입니다.

---

먼저 결정할 것: Skill인가, Plugin인가?

Codex에 새로운 동작을 추가하려고 할 때 가장 먼저 구분해야 하는 것은 Skill과 Plugin의 역할입니다.

Skill

Skill은 특정 요청이 들어왔을 때 Codex가 따라야 하는 작업 지침입니다. 사용자가 자연어로 특정 작업을 요청하면, Skill에 정의된 절차와 규칙을 기준으로 작업을 수행합니다.

예를 들어 다음과 같은 요청을 반복적으로 처리하고 싶다면 Skill이 적합합니다.

bcpprm 해줘

이 요청이 들어왔을 때 Codex가 Git 상태를 확인하고, 브랜치·커밋·Push·PR 생성 절차를 정해진 규칙대로 수행하도록 만들 수 있습니다.

Plugin

Plugin은 Skill뿐 아니라 assets, metadata 등 여러 구성 요소를 묶어 관리하는 패키지에 가깝습니다. 하나의 단순한 워크플로를 추가하려는 상황이라면 오히려 구조가 과해질 수 있습니다.

무엇을 선택해야 할까?

필요한 기능	권장 방식
브랜치 생성, 커밋, PR 작성처럼 정해진 작업 절차 자동화	Skill
여러 기능과 리소스를 함께 배포·관리하는 패키지	Plugin 고려

 

bcpprm 역시 처음에는 Plugin 형태를 고려했지만, 최종적으로는 자연어 요청에 반응해 하나의 Git/PR 워크플로를 수행하는 기능이므로 Skill로 정리했습니다.

---

Codex Skill의 기본 설치 위치와 구조

새로운 Skill은 사용자 홈 디렉터리 아래의 Codex Skill 경로에 둡니다.

~/.codex/skills/<skill-name>/

 

bcpprm의 실제 설치 경로는 다음과 같습니다.

/Users/username/.codex/skills/bcpprm/

 

Skill의 최소 구조는 매우 단순합니다.

~/.codex/skills/<skill-name>/
└── SKILL.md

 

다만 브랜치명 규칙, 커밋 메시지 규칙, PR 템플릿처럼 별도로 관리할 설정이 있다면 assets/ 디렉터리를 함께 두는 방식이 좋습니다.

~/.codex/skills/<skill-name>/
├── SKILL.md
└── assets/
    ├── conventions.json
    └── conventions.md

 

bcpprm는 다음 구조로 구성했습니다.

/Users/username/.codex/skills/bcpprm/
├── SKILL.md
└── assets/
    ├── conventions.json
    └── conventions.md

 

이 구조의 핵심은 동작 지침과 규칙 데이터를 분리하는 것입니다. Skill의 전체 흐름은 SKILL.md가 담당하고, 반복적으로 수정될 수 있는 Git·PR 규칙은 assets/에서 별도로 관리합니다.

---

Step 1: Skill 이름 정하기

Skill 이름은 이후 여러 위치에서 동일한 식별자로 사용됩니다.

• Skill 디렉터리 이름
• SKILL.md frontmatter의 name
• 사용자가 자연어 요청에서 언급할 키워드

따라서 이름은 짧고, 기억하기 쉽고, 요청문에 자연스럽게 넣을 수 있어야 합니다.

이름을 정할 때의 기준

• 영문 소문자 사용을 권장한다.
• 공백 없이 작성한다.
• 수행하는 작업을 연상할 수 있는 이름으로 짓는다.
• 너무 일반적인 단어보다는 고유한 트리거가 되는 이름이 좋다.

bcpprm는 Branch, Commit, Push, Pull Request 흐름을 빠르게 떠올릴 수 있는 이름으로 정했습니다.

bcpprm

 

이후 사용자는 다음처럼 요청할 수 있습니다.

bcpprm 해줘

---

Step 2: 핵심 파일 SKILL.md 만들기

SKILL.md는 Skill의 핵심 파일입니다. Codex가 언제 이 Skill을 적용해야 하는지, 적용된 뒤 어떤 순서와 규칙으로 작업해야 하는지를 정의합니다.

가장 기본적인 형태는 다음과 같습니다.

---
name: myskill
description: Use when ...
---

# My Skill

이 스킬이 수행할 작업과 규칙을 작성합니다.

Frontmatter에서 중요한 두 필드

필드	역할
name	Skill의 식별자
description	어떤 사용자 요청에서 Skill을 적용해야 하는지 설명하는 트리거 정의

 

여기서 특히 중요한 것은 description입니다. Skill이 잘 만들어져 있어도 사용자의 요청과 연결되지 않으면 동작을 기대하기 어렵습니다. 따라서 실제 사용자가 말할 법한 표현을 구체적으로 포함하는 것이 좋습니다.

bcpprm의 frontmatter 예시

---
name: bcpprm
description: Use when the user mentions `bcpprm`, tries `/bcpprm`, or asks to create a branch, commit, push, and draft or create a pull request ...
---

 

이 정의에는 다음 의도가 담겨 있습니다.

• 사용자가 bcpprm라는 이름을 직접 말했을 때 감지한다.
• 사용자가 /bcpprm처럼 입력했을 때도 관련 요청으로 해석할 수 있게 한다.
• Skill 이름을 모르더라도 “브랜치 만들고 커밋하고 PR 올려줘” 같은 자연어 요청을 감지할 여지를 둔다.

 

단, 여기서 주의해야 할 점이 있습니다. description에 /bcpprm을 포함했다고 해서, 이것이 곧바로 Codex의 내장 Slash Command로 등록되는 것은 아닙니다. 이 차이는 뒤에서 다시 다루겠습니다.

---

Step 3: Skill 본문에 실제 워크플로 정의하기

Frontmatter가 “언제 이 Skill을 사용할 것인가”를 정의한다면, 본문은 “Skill이 선택된 뒤 무엇을 할 것인가”를 정의합니다.

Skill 본문에는 최소한 다음 요소를 담는 것이 좋습니다.

• 작업 수행 순서
• 반드시 지켜야 하는 동작 규칙
• 트리거 예시
• 최종 출력 또는 완료 조건
• 위험한 작업에 대한 승인 규칙

재사용 가능한 기본 템플릿은 다음과 같이 만들 수 있습니다.

# Skill Name

이 스킬은 다음 순서로 동작합니다.

1. 현재 상태 확인
2. 필요한 규칙 파일 읽기
3. 작업 내용 결정
4. 변경 작업 실행
5. 실행 결과 보고

## 필수 동작

- ...

## 트리거 예시

- `myskill 해줘`

## 완료 조건

- ...

bcpprm에 정의한 작업 흐름

bcpprm는 Git 변경 사항을 PR로 연결하는 Skill이므로, 아래와 같은 순서로 동작하도록 구성했습니다.

1. 현재 Git 상태와 변경 사항을 확인한다.
2. assets/ 아래의 규칙 파일을 읽는다.
3. 변경 내용을 바탕으로 브랜치명을 결정한다.
4. 스테이징 대상 파일을 확인한 뒤 git add를 수행한다.
5. 규칙에 맞는 커밋 메시지를 생성하고 커밋한다.
6. 원격 저장소로 브랜치를 Push한다.
7. 이미 생성된 PR이 있는지 확인한다.
8. PR이 없다면 정해진 형식에 따라 새 PR을 생성한다.

이처럼 본문에는 단순히 “PR을 만들어라”가 아니라, 실제 작업에서 놓치면 안 되는 상태 확인과 중복 확인 과정까지 포함시키는 것이 중요합니다.

---

Step 4: 변할 수 있는 규칙은 assets/로 분리하기

Skill을 작성하다 보면 동작 자체는 같지만, 팀이나 프로젝트에 따라 달라지는 규칙이 있습니다.

예를 들어 다음 항목들은 자주 변경될 수 있습니다.

• 브랜치명 패턴
• 커밋 메시지 컨벤션
• PR 제목 형식
• PR 본문 섹션
• 기본 대상 브랜치

이런 내용을 SKILL.md 본문에 모두 직접 적어두면, 규칙이 변경될 때마다 동작 설명까지 함께 수정해야 합니다. 반대로 규칙을 별도 asset으로 분리하면 Skill의 흐름은 유지하면서 설정만 바꿀 수 있습니다.

 

권장하는 asset 구성

파일	용도
conventions.json	Codex가 구조적으로 참고할 수 있는 규칙 데이터
conventions.md	사람이 읽고 수정하기 쉬운 설명과 예시

 

bcpprm의 규칙 예시

bcpprm에서는 다음과 같은 규칙을 asset으로 관리했습니다.

항목	규칙
브랜치명	type/summary
커밋 메시지	type: summary
PR 제목	[TYPE] 제목
기본 대상 브랜치	main
PR 본문 섹션	요약, 작업내용, 변경파일, 검증, 비고

왜 JSON과 Markdown을 함께 두는가?

conventions.json은 구조가 명확하기 때문에 자동화 규칙으로 참고하기 좋습니다. 반면 conventions.md는 사람이 컨벤션의 배경과 예시를 이해하거나 직접 수정할 때 훨씬 편리합니다.

즉, 두 파일은 중복이 아니라 목적이 다릅니다.

• JSON: 작업 수행 시 참조할 수 있는 명시적인 규칙
• Markdown: 규칙을 유지보수하는 사람을 위한 설명서

---

각 파일의 역할을 명확히 나누기

Skill을 만들 때 파일 수가 늘어나면 “어떤 내용을 어디에 두어야 하는가?”가 애매해질 수 있습니다. bcpprm를 기준으로 파일의 책임을 정리하면 다음과 같습니다.

파일	책임	bcpprm에서의 역할
SKILL.md	Codex가 수행할 워크플로와 사용 조건 정의	Git 상태 확인부터 PR 생성까지의 절차 정의
assets/conventions.json	기계적으로 읽기 쉬운 규칙 데이터	브랜치명·커밋 메시지·PR 형식 정의
assets/conventions.md	사람을 위한 설명과 예시	컨벤션의 의미와 작성 예시 기록

 

이렇게 책임을 분리해 두면 새로운 Skill을 만들 때에도 같은 패턴을 재사용할 수 있습니다.

예를 들어 배포 자동화 Skill이라면 SKILL.md에 배포 절차를 두고, assets/에는 대상 환경, 브랜치 정책, 검증 체크리스트 등을 둘 수 있습니다.

---

Step 5: 등록 후에는 새 세션에서 테스트하기

Skill 파일을 생성했다고 해서 현재 열려 있는 Codex 세션이 즉시 새로운 Skill을 반영한다고 가정하면 안 됩니다. 이미 실행 중이던 세션은 새로 추가된 Skill을 다시 읽지 않을 수 있기 때문입니다.

따라서 Skill 등록 이후에는 새 Codex 세션을 열어 테스트하는 과정을 권장합니다.

테스트 순서

1. 새로운 Codex 세션을 연다.
2. Skill 이름을 직접 포함한 요청을 보낸다.
3. 이름 없이 작업 의도만 담은 자연어 요청도 테스트한다.
4. 실제로 정의한 규칙 파일과 워크플로가 반영되는지 확인한다.

bcpprm 테스트 요청 예시

bcpprm 해줘

bcpprm 규칙대로 진행해줘

현재 변경 사항으로 브랜치 만들고 커밋한 뒤 PR까지 작성해줘

 

마지막 요청까지 잘 처리된다면, Skill 이름에만 의존하지 않고 작업 의도에 따라 선택될 수 있도록 description이 충분히 작성되어 있는지 확인하는 데 도움이 됩니다.

---

등록 여부를 확인하는 방법

테스트 전에 가장 먼저 확인할 것은 실제 파일이 올바른 위치에 생성되어 있는지입니다.

bcpprm의 경우 확인 대상 파일은 다음과 같습니다.

/Users/username/.codex/skills/bcpprm/SKILL.md
/Users/username/.codex/skills/bcpprm/assets/conventions.json
/Users/username/.codex/skills/bcpprm/assets/conventions.md

 

그 다음에는 Codex 환경에서 Skill 목록에 표시되는지 확인하고, 새 세션에서 트리거 요청을 실행합니다.

확인 체크포인트

• 폴더명이 SKILL.md의 name과 일치하는가?
• SKILL.md가 올바른 경로에 존재하는가?
• description에 실제 사용할 요청 표현이 포함되어 있는가?
• asset 파일을 읽도록 본문에 명시되어 있는가?
• 새 세션에서 Skill이 적용되는가?

Codex 버전이나 실행 환경에 따라 Skill 목록을 확인하는 UI나 명령 노출 방식은 달라질 수 있으므로, 최종적으로는 새 세션에서 실제 요청이 의도한 흐름으로 처리되는지를 기준으로 판단하는 것이 가장 안전합니다.

 

모두 확인 후 입력창에 /skills -> List skills 결과, bcpprm이 보이면 정상적으로 등록된 것입니다.

---

원격 저장소를 변경하는 Skill에는 승인 규칙을 넣자

bcpprm처럼 Git Push 또는 PR 생성을 포함하는 Skill은 단순한 문서 요약 Skill과 성격이 다릅니다. 실행 결과가 로컬에만 머물지 않고 원격 저장소에 영향을 주기 때문입니다.

 

따라서 다음과 같은 작업을 수행하는 Skill에는 승인 규칙과 실패 대응 방법을 명시하는 것이 좋습니다.

• git push
• git push --force-with-lease
• gh pr create
• 배포 실행
• 원격 리소스 수정 또는 삭제

GitHub CLI(gh)가 필요한 이유

bcpprm의 마지막 단계는 GitHub Pull Request를 확인하고, 필요한 경우 새 PR을 생성하는 작업입니다. git 명령어만으로 브랜치 생성, 커밋, 원격 저장소 Push까지는 처리할 수 있지만, GitHub 위에서 PR을 조회하거나 생성하려면 GitHub 서비스와 상호작용할 수 있는 도구가 필요합니다.

 

이때 사용하는 도구가 GitHub CLI, 즉 gh입니다. gh를 이용하면 브라우저를 열어 수동으로 PR을 작성하지 않아도 터미널에서 인증 상태 확인, 기존 PR 조회, 새 PR 생성까지 이어서 수행할 수 있습니다.

명령어	역할
gh auth status	현재 환경에서 GitHub 계정 인증 상태 확인
gh pr list --head <branch-name>	해당 브랜치로 이미 생성된 PR이 있는지 확인
gh pr create --base main --title "[TYPE] 제목" --body-file <pr-body-file>	규칙에 맞는 제목과 본문으로 PR 생성

 

예를 들어 인증 상태는 다음 명령으로 확인할 수 있습니다.

gh auth status

 

현재 브랜치로 이미 생성된 PR이 있는지는 다음처럼 확인할 수 있습니다.

gh pr list --head <branch-name>

 

기존 PR이 없고 새로 생성해야 한다면 다음과 같이 대상 브랜치, 제목, 본문을 지정할 수 있습니다.

gh pr create --base main --title "[TYPE] 제목" --body-file <pr-body-file>

 

bcpprm에서 git과 gh가 담당하는 역할

bcpprm는 로컬 변경 사항을 GitHub PR까지 연결하는 워크플로입니다. 이 과정에서 git과 gh는 서로 다른 범위를 담당합니다.

도구	담당 범위
git	로컬 변경 사항 확인, 브랜치 생성, 스테이징, 커밋, 원격 저장소 Push
gh	GitHub 인증 상태 확인, 기존 PR 조회, 새 PR 생성

 

전체 흐름은 다음처럼 이어집니다.

git status
→ git checkout -b <branch-name>
→ git add <files>
→ git commit -m "<commit-message>"
→ git push -u origin <branch-name>
→ gh auth status
→ gh pr list --head <branch-name>
→ gh pr create ...

 

단, 모든 경우에 gh pr create를 바로 실행하는 것은 적절하지 않습니다. 이미 같은 브랜치로 생성된 PR이 있다면 새 PR을 중복 생성하는 대신 기존 PR을 안내하거나 갱신된 커밋이 반영되었는지 확인해야 합니다.

bcpprm에 적용할 수 있는 안전 규칙

• Push 또는 PR 생성 전에 사용자 승인을 받도록 한다.
• 강제 Push가 필요하다면 일반 Push보다 더 엄격하게 확인한다.
• PR 작업 전에 gh auth status로 GitHub CLI 인증 상태를 점검할 수 있도록 한다.
• gh pr create 실행 전, 현재 브랜치에 연결된 기존 PR이 있는지 먼저 확인한다.
• 인증 실패나 권한 부족으로 PR 생성이 실패하면 로그인 상태와 저장소 접근 권한을 우선 점검한다.

이러한 규칙은 작업을 느리게 만들기 위한 것이 아니라, 자동화 범위가 커질수록 발생할 수 있는 원격 저장소 변경 실수와 중복 작업을 통제하기 위한 장치입니다.

 

bcpprm 테스트

 

branch 명명 규칙부터 commit, PR 메시지 convention 모두 지켜서 workflow를 제대로 수행한 것을 확인할 수 있습니다.

---

Skill과 Slash Command는 다르다

Skill을 처음 등록할 때 가장 혼동하기 쉬운 부분은 Slash Command와의 차이입니다.

Skill은 자연어 요청을 바탕으로 특정 작업 지침을 적용하는 방식입니다. 반면 Slash Command는 별도로 등록되거나 제품이 제공하는 명령 체계입니다.

 

따라서 Skill 이름이 bcpprm라고 해서 자동으로 다음 명령이 내장 명령처럼 동작하는 것은 아닙니다.

/bcpprm

 

하지만 SKILL.md의 description에 관련 표현을 넣고, 자연어 요청으로 다음과 같이 사용할 수 있습니다.

bcpprm 해줘

 

정리하면 bcpprm의 현재 형태는 다음과 같습니다.

구분	해당 여부
Codex Skill	O
Plugin	X
내장 Slash Command	X
자연어 트리거 기반 워크플로	O

---

Plugin으로 시작했다가 Skill만 남기고 싶을 때

처음에는 구조를 넓게 잡아 Plugin으로 만들었다가, 실제로는 Skill 하나만 있으면 충분하다고 판단할 수도 있습니다. bcpprm 역시 이런 정리 과정을 거쳤습니다.

Plugin을 걷어내고 Skill만 유지하려면 다음 순서로 정리할 수 있습니다.

1. Plugin 안에서 필요한 SKILL.md와 assets/ 파일만 추출한다.
2. ~/.codex/skills/<skill-name>/ 경로에 복사한다.
3. 기존 Plugin 디렉터리를 삭제한다.
4. 로컬 marketplace 등에 등록된 Plugin 항목을 제거한다.
5. 새 Codex 세션에서 Skill 단독으로 동작하는지 검증한다.

bcpprm에서는 다음 항목을 제거했습니다.

~/vscode/plugins/bcpprm
~/vscode/.agents/plugins/marketplace.json 내부의 bcpprm 항목

 

이 과정을 통해 최종 구조는 Plugin 의존 없이 ~/.codex/skills/bcpprm/ 아래의 파일만으로 관리되는 형태가 되었습니다.

---

다른 Skill을 만들 때 그대로 재사용할 체크리스트

새로운 Skill을 등록할 때마다 아래 항목을 순서대로 확인하면 빠뜨리는 부분을 줄일 수 있습니다.

설계 단계

• 수행하려는 기능이 Skill에 적합한 단일 워크플로인가?
• 여러 기능과 리소스를 패키지로 관리해야 한다면 Plugin이 더 적합하지 않은가?
• 사용자가 자연어로 부르기 쉬운 Skill 이름을 정했는가?

파일 작성 단계

• ~/.codex/skills/<skill-name>/ 디렉터리를 만들었는가?
• SKILL.md에 name을 정확히 작성했는가?
• description에 실제 요청문과 유사한 트리거 표현을 넣었는가?
• 작업 순서, 완료 조건, 필수 규칙을 본문에 명시했는가?
• 변경될 수 있는 규칙을 assets/로 분리할 필요가 있는가?

검증 단계

• 새 Codex 세션에서 테스트했는가?
• Skill 이름을 포함한 요청과 자연어 작업 요청을 모두 시험했는가?
• 원격 변경 작업이 있다면 승인 절차를 포함했는가?
• 실패 시 확인할 인증·환경 점검 방법을 적어두었는가?

---

최종 정리: "좋은 Skill은 작업 지시서이자 운영 규칙이다"

bcpprm를 등록하면서 가장 중요했던 점은 단순히 “브랜치와 PR을 자동으로 만들어주는 기능”을 추가하는 것이 아니었습니다. 실제로 반복 가능한 Skill을 만들기 위해서는 다음 요소가 함께 필요했습니다.

• 사용자의 요청을 안정적으로 감지할 수 있는 구체적인 description
• 순서가 명확한 SKILL.md 워크플로
• 자주 바뀌는 컨벤션을 분리한 assets/ 구조
• 새 세션에서의 실제 동작 검증
• Push와 PR 생성 같은 원격 작업에 대한 안전 규칙

즉, Skill은 단순한 프롬프트 조각이 아니라 반복 작업을 신뢰할 수 있게 수행하도록 만드는 작은 운영 문서에 가깝습니다.

현재 bcpprm는 다음 세 파일을 중심으로 동작하는 자연어 트리거 기반 Codex Skill입니다.

~/.codex/skills/bcpprm/
├── SKILL.md
└── assets/
    ├── conventions.json
    └── conventions.md

 

앞으로 배포 체크, 코드 리뷰 준비, 문서 생성, 테스트 실행처럼 반복되는 개발 작업이 생긴다면, 같은 구조로 새로운 Skill을 설계해볼 수 있습니다.

 

작업 순서를 명시하고, 변하는 규칙을 asset으로 분리하고, 위험한 동작에는 승인 기준을 두는 것.

 

이 세 가지를 지키면 특정 사례를 넘어 재사용 가능한 자동화 워크플로로 발전시킬 수 있습니다.