B컷전문 | 개발과 인생의 이야기

같은 저장소를 열 때마다 테스트 명령, 코드 리뷰 기준, 릴리스 절차를 다시 설명하고 있지는 않은가? 한 번은 잘 전달해도, 다음 대화에서는 일부가 빠지거나 표현이 달라진다. 이런 반복 업무를 에이전트가 필요할 때 읽어 실행할 수 있도록 묶은 것이 스킬(skill)이다.

Claude Code와 Codex는 모두 스킬을 재사용 가능한 작업 흐름으로 다루며, 중심에는 SKILL.md가 있다. 하지만 스킬은 모델을 새로 학습시키거나 권한을 자동으로 부여하는 기능이 아니다. 무엇을 언제 어떻게 할지 안내하고, 필요한 경우 보조 자료와 스크립트를 함께 제공하는 작은 워크플로 패키지에 가깝다.

먼저 보는 시리즈 목차

1. 스킬이란 무엇인가: Claude Code와 Codex의 공통 구조
2. Claude Code에서 스킬 만들기: 위치와 호출 방식
3. Codex에서 스킬 만들기: 프로젝트·사용자 범위와 발견 경로
4. 좋은 SKILL.md 쓰기: 이름, 설명, 입력과 완료 조건
5. 긴 지침을 나누는 법: 참고 자료와 스크립트를 활용한 점진적 공개
6. 자동 호출과 명시 호출: 권한·부작용 경계 설계
7. Claude와 Codex에서 함께 쓰기: 공통 포맷과 제품별 확장 비교
8. 실전 스킬 개선: 사례 테스트, 보안 검토, 배포와 유지보수

스킬은 프롬프트 복사본보다 ‘업무 절차’에 가깝다

예를 들어 “코드를 리뷰해줘”라는 일반 요청은 저장소마다 다른 규칙을 놓칠 수 있다. 반면 코드 리뷰 스킬에는 먼저 변경 범위를 확인하고, 테스트와 보안 경계에 맞춰 살핀 뒤, 문제를 심각도와 근거를 붙여 정리한다는 순서를 담을 수 있다. 팀의 관례를 대화마다 복사하지 않아도 되고, 수정할 때도 한곳을 고치면 된다.

두 제품의 스킬은 공통적으로 지침과 부가 자원을 묶지만, 설치 경로나 제품 전용 메타데이터까지 완전히 같다고 가정하면 안 된다. Claude Code는 프로젝트 스킬을 .claude/skills/<skill-name>/SKILL.md, 사용자 스킬을 ~/.claude/skills/에 둔다. Codex는 저장소 안의 .agents/skills/와 사용자 범위의 ~/.agents/skills/ 등에서 스킬을 찾는다. 상세 동작은 사용하는 제품·버전의 공식 문서를 확인하는 편이 안전하다.

SKILL.md의 기본 구조

두 도구 모두 스킬을 디렉터리로 구성할 수 있다. 기본 파일은 YAML frontmatter와 본문 지침으로 나뉜다. 예를 들어 저장소의 테스트 규칙을 담는 스킬은 다음처럼 시작할 수 있다.

---
name: repo-test-guide
description: Run the repository's relevant tests and summarize failures. Use when changing code or checking a pull request.
---

## Workflow
1. Read the repository's test instructions.
2. Identify the smallest relevant test set.
3. Run tests and report the exact command and result.
4. If a test fails, summarize evidence; do not claim success.

name은 짧고 알아보기 쉬운 식별자, description은 어떤 작업에서 이 스킬을 선택해야 하는지 알려주는 설명이다. 자동 선택은 설명에 크게 좌우되므로 “개발을 돕는다”처럼 넓게 쓰기보다 작업, 상황, 경계를 구체적으로 적자. Claude Platform의 작성 지침도 목적과 트리거가 드러나는 설명을 권한다.

스킬을 여러 파일로 나눌 수도 있다. SKILL.md에는 핵심 절차와 다음에 읽을 자료를 두고, 세부 규칙은 references/, 반복 실행이 정확해야 하는 작업은 scripts/, 템플릿은 assets/처럼 분리한다. 모든 내용을 한 파일에 넣는 대신 필요한 순간에만 상세 자료를 읽게 하는 방식이다.

명시적으로 부를지, 상황에 맞춰 자동 선택하게 할지

Claude Code에서는 보통 /skill-name으로 직접 실행하고, 설명이 요청과 맞으면 자동으로 선택될 수도 있다. Codex에서는 프롬프트에 스킬을 직접 지정하거나, 환경에 따라 CLI·IDE에서 스킬을 선택할 수 있고, 설명과 작업이 맞을 때 자동 선택도 가능하다. 정확한 조작 방식은 제품 인터페이스에 따라 달라질 수 있다.

자동 선택이 편리하다고 모든 스킬을 자동으로 실행하게 만들 필요는 없다. 배포, 커밋, 외부 전송처럼 부작용이 있는 절차는 사람이 호출 시점을 통제하도록 설계하고, 스킬 지침만으로 권한 검사를 대신하지 말자. 실제 파일 변경이나 명령 실행은 도구 권한과 승인 정책의 적용을 받는다.

첫 스킬은 작고 검증 가능하게

처음부터 “개발 전 과정을 처리하는 만능 스킬”을 만들기보다, 자주 반복되고 완료 여부를 확인할 수 있는 한 가지 일부터 시작하자. 예컨대 “변경된 모듈의 테스트를 찾아 실행하고, 실패를 요약한다”처럼 범위를 좁힌다.

• 무엇을 입력으로 받는지 적는다. 예: 현재 브랜치의 코드 변경
• 절차를 순서대로 적고, 불확실할 때의 행동도 정한다.
• 성공의 증거를 적는다. 예: 실행한 테스트 명령과 종료 결과
• 저장소에서 실제 요청 몇 가지로 테스트해 누락과 과잉 호출을 확인한다.
• 틀린 결과를 바탕으로 description과 지침을 고친다.

공식 문서를 보면 Codex는 스킬 디렉터리 안에 SKILL.md 외에도 선택적 스크립트, 참고자료, 자산 파일을 둘 수 있고, Claude Code는 Agent Skills 표준을 따르면서 제품별 호출 제어 같은 확장을 제공한다. 따라서 “공통으로 읽히는 핵심 지침”과 “특정 제품에서만 쓰는 확장”을 의식적으로 구분하는 것이 이식성에 도움이 된다.

요약

스킬은 자주 반복하는 일을 재현 가능한 절차로 정리해 에이전트가 필요한 때 활용하도록 만드는 패키지다. SKILL.md에 분명한 이름과 선택 기준을 적고, 긴 참고 내용과 실행 스크립트는 필요에 따라 분리한다. Claude Code와 Codex는 비슷한 기본 개념을 공유하지만, 경로·호출·제품별 메타데이터는 다를 수 있다. 작은 업무 하나로 시작해 실제 사용 결과를 확인하고 고쳐 나가자.

참고 자료

• Claude Code Docs: Extend Claude with skills
• Claude Platform Docs: Skill authoring best practices
• OpenAI Developers: Agent Skills for Codex
• Agent Skills: Specification