Agent Skills 추천과 사용 가이드：2026 설치 방법, Claude Code / Codex에 넣을 스킬

2026년 9월이면 Claude Code, Codex, Cursor와 여러 오픈소스 Coding Agent가 같은 개방 형식을 쓴다. 디렉터리 하나와 SKILL.md다. 스킬은 「또 하나의 플러그인 시장」이 아니다. 필요할 때만 로드하는 절차 설명서다. 많은 팀이 여전히 릴리스 점검, 리뷰 단계, 롤백 구호를 CLAUDE.md나 AGENTS.md에 붙여 넣거나, GitHub에서 커뮤니티 팩을 수십 개 원클릭으로 깐다. 사야 하는 질문은 몇 개를 넣었느냐가 아니다. 그 절차를 매 턴 컨텍스트에 넣을지, description이 다른 일에서 오발하는지, 폴더의 scripts/가 실행 사용자와 같은 권한으로 도는지다. 이 글은 개방 표준 전문을 되풀이하지 않는다. 설치와 선정만 답한다. Claude Code와 Codex에 무엇을 넣고, 어떻게 넣고, 어떻게 검수할지.

왜 전역 프롬프트에 절차를 계속 넣으면 이미 틀린 선택인가

옛 방식과 새 방식은 구체적으로 충돌한다. 옛 방식은 프롬프트 우선이다. 저장소 뿌리에 점점 길어지는 한 권의 매뉴얼을 두고, 매 세션 전문을 모델에 넣는다. 새 방식은 스킬 우선이다. 안정된 사실은 CLAUDE.md / AGENTS.md에 남기고, 반복되는 다단계 절차는 SKILL.md로 만든다. Agent는 먼저 이름과 설명만 보고, 쓸 때만 본문을 로드한다. 같은 「이번 릴리스를 내보내」라도 옛 방식은 매 턴 설명서 값을 내고, 새 방식은 릴리스 과제에서만 낸다.

이게 취미가 아니라 일정 우선순위가 된 이유는 세 가지다. 첫째, Claude Code는 사용자 슬래시 명령을 Skills에 합쳤다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md 모두 /deploy가 된다. 옛 명령 파일은 계속 동작한다. 부가 파일, 자동 트리거, 하위 Agent라는 새 능력은 스킬 디렉터리에만 있다. 둘째, Codex는 개방 표준대로 .agents/skills를 현재 디렉터리에서 저장소 뿌리까지 위로 스캔한다. 개인 스킬은 ~/.agents/skills다. 옛 경로 ~/.codex/skills도 여전히 본다. 디렉터리를 잘못 쓰면 「깔았는데 호출이 안 된다」로 나타난다. 셋째, Vercel의 npx skills는 같은 팩을 Claude Code, Codex, Cursor 등 수십 개 Agent 디렉터리에 쓸 수 있다. 교차 재사용이 성립하는 전제는, 한 업체의 사설 frontmatter에만 맞춰 쓰지 않는 것이다.

자주 빠뜨리는 층이 있다. Skills는 MCP도 아니고 Function Calling도 아니다. MCP와 도구 프로토콜은 「모델이 살아있는 인터페이스를 어떻게 호출하는가」를 다룬다. 스킬은 「이 사람 절차를 언제 로드하는가」를 다룬다. 프로토콜 층 설계는 Function Calling이란에서 보라. 세션을 넘는 동적 상태도 스킬 본문에 넣지 마라. 그건 기억 층의 일이고 자체 Agent Memory vs SaaS에서 다룬다. 하니스 자체 선정은 Pi vs Claude Code vs Codex를 보라.

Agent Skills를 어떻게 분류하는가

스킬 이름을 나란히 놓으면 즐겨찾기는 반드시 부푼다. 누가 유지하는가, 언제 로드되는가, 부작용이 있는가로 셋을 나눠라. 한 칸이 빠지면 평판만 남는다.

Claude Code 번들 스킬은 프롬프트 편성이지 고정 바이너리가 아니다. /code-review, /debug, /run, /verify, /run-skill-generator, /doctor. 뒤 셋은 v2.1.145부터 README나 package.json으로 기동 방식을 추론할 수 있다. 복잡한 프로젝트는 /run-skill-generator를 한 번 돌려 설치 명령, 환경 변수, 기동 스크립트를 저장소 안 스킬로 써라. 매번 다시 발견하지 않게. Codex가 묶는 것은 skill-installer, skill-creator, review-agent, openai-docs 같은 안내기다. 양쪽 모두 「이름과 설명을 먼저 보고, 쓸 때 본문을 읽는다」는 점진 공개를 따른다. description 칸은 장식이 아니다. 너무 짧으면 발화하지 않고, 너무 넓으면 잡일에도 발화한다.

핵심 비교: 입구, 실행, 컨텍스트, 대상

진짜 차이는 입구다. 어느 연구소의 스킬 목록이 더 큰지가 아니다. 세 장은 같은 열 이름으로 맞춰라.

둘째 표는 「깔린 줄 알았다」는 함정만 메운다. 열 이름은 맞춘다. 빈 형용사로 흐르지 않게.

# Claude Code — project skill (this repo only)
mkdir -p .claude/skills/review-change

# Codex — project skill (open .agents/ convention)
mkdir -p .agents/skills/review-change

# Personal skill, every repo on this machine
mkdir -p ~/.claude/skills/review-change
mkdir -p ~/.agents/skills/review-change

# Cross-agent package manager (Vercel skills CLI)
npx skills add vercel-labs/agent-skills --skill react-best-practices -a claude-code
npx skills add vercel-labs/agent-skills --skill react-best-practices -a codex

# Codex bundled installer (often writes ~/.codex/skills)
# Inside a Codex session:
# $skill-installer linear

최소 SKILL.md에 필요한 것은 개방 표준의 name과 description뿐이다. 아래 파일로 「발화하는지, 본문을 읽는지」를 검수할 수 있다. 그 루프가 지루해질 때까지 scripts/를 넣지 마라.

---
name: review-change
description: Reviews an uncommitted diff and lists risks. Use when the user asks what changed, wants a commit message, or asks to review the working tree. Do not use for greenfield feature design.
---

## Current changes

Run git diff HEAD and summarize in three bullets.
Flag missing tests, hardcoded secrets, and edits outside the named module.
If the diff is empty, say so and stop.

Claude Code / Codex에 실제로 넣을 스킬

추천 조합은 공식 상점 Top 10이 아니다. 부작용 사다리다. 번들 스킬은 남겨 둔다. 프로젝트 스킬은 매주 반복하는 절차만 남긴다. 교차 규범은 본문을 읽은 것만 넣는다.

개인 개발자는 먼저 review-change 하나와 release 하나를 두고, 그다음에 React 규범이 필요한지 정한다. 소규모 팀은 「PR 전에 반드시 돌릴 검사」를 프로젝트 스킬로 쓰고, 개인 취향은 사용자급 CLAUDE.md에 남긴다. 고객 경로를 사용자급 스킬에 넣지 마라. 기업은 스킬을 코드로 다룬다. PR에서 SKILL.md와 scripts/를 본다. 감사하지 않은 팩을 ~/.agents/skills에 연결하는 구성원을 허용하지 마라.

장면으로 고르는 법

추천 조합

A — 개인 개발자, 주 CLI 하나: 번들 스킬은 켜 둔다. 저장소에 커밋하는 프로젝트 스킬은 둘뿐이다. 커밋하지 않은 diff 리뷰, 기존 스크립트로 릴리스. description에 「언제 쓸지 / 언제 쓰지 말지」를 쓴다. 파일 쓰기와 bash는 컨테이너, 또는 세션마다 격리하는 원격 Mac에 둔다. 노드 월 요금과 요금제 대조는 Mac mini 가격.

B — 소규모 제품 팀, Claude Code + Codex 병존: 규범 스킬은 npx skills로 Agent마다 react-best-practices 또는 web-design-guidelines를 넣는다. 카탈로그 통째로 넣지 마라. 릴리스와 롤백은 프로젝트 디렉터리에만 두고 PR에서 본다. 개인 말버릇은 사용자급 프롬프트에 남기고 스킬에 넣지 마라. 두 CLI를 같은 샘플 릴리스 과제로 검수한다. 「한쪽에서 되면 다른 쪽도 된다」고 가정하지 마라.

C — 기업 또는 고보안: 스킬을 코드로 다룬다. 디렉터리, 스크립트, 설명은 PR을 통과한다. 사용자 폴더에 감사하지 않은 팩을 연결하지 마라. 네트워크나 비밀을 건드리는 스크립트는 폐기 가능한 노드에서만 돌린다. 계정과 인도 경계는 도움말 센터. 격리 작업 공간이 필요하면 일상 노트북을 실험장으로 쓰지 말고 Mac mini 대여에서 노드를 보라.

흔한 오해

1. 즐겨찾기로 고른다: 「많이 깔수록 Agent가 일을 더 한다」. 넓은 description마다 오발 예산이다.
2. 절차를 전역 프롬프트에 남긴다: 매 세션 실리는 릴리스 점검은 매 턴 내는 설명서 값이다.
3. 경로가 통용된다고 가정한다: Claude Code의 .claude/skills는 Codex의 기본 뿌리가 아니다. Codex 설치기는 여전히 ~/.codex/skills에 쓸 수 있다.
4. 스크립트를 읽지 않고 사용자급에 넣는다: scripts/는 실행 사용자 권한을 이어받는다. 먼저 프로젝트, 먼저 격리 노드.
5. 커뮤니티 스킬로 테스트를 대체한다: /verify와 자체 CI는 대체재가 아니다. 스킬은 적녹 테스트를 대신하지 못한다.

도입 단계: 7단계

1. CLAUDE.md / AGENTS.md를 열고 한 단락을 넘는 절차를 후보로 표시한다. 릴리스, 리뷰, 롤백, 변경 설명. 사실은 남기고 단계는 옮긴다.
2. scripts/ 없는 SKILL.md를 하나 쓴다. description에 「언제 쓸지 / 언제 쓰지 말지」를 쓴다. /review-change 또는 $review-change로 한 번 수동 발화한다.
3. 평범한 구어로 다시 물어 자동 트리거를 본다. 오발이면 설명을 고친다. 두 번째 스킬을 깔아 덮지 마라.
4. Claude Code는 .claude/skills/, Codex는 .agents/skills/. Cursor 등 다른 Agent에도 보여야 하면 npx skills add … -a. 손으로 잘못된 디렉터리에 베끼지 마라.
5. 번들 스킬에 프로젝트 스킬 2–4개에서 멈춘다. 커뮤니티 팩은 SKILL.md와 스크립트를 읽은 뒤에만 프로젝트에 넣는다. ~/.claude/skills나 ~/.agents/skills를 먼저 쓰지 마라.
6. scripts/가 있는 스킬은 컨테이너나 원격 Mac에서 먼저 돌린다. 비밀은 프롬프트에도 스킬 본문에도 넣지 마라. 세션이 끝나면 작업 공간을 지울 수 있어야 한다.
7. 같은 릴리스 또는 리뷰 과제로 검수한다. 발화했는지, 어떤 파일을 건드렸는지, 자체 CI가 초록인지. 따뜻한 로컬 캐시의 「초록처럼 보임」은 검수가 아니다.

FAQ

Skills와 CLAUDE.md / AGENTS.md는 무엇이 다른가?

안정된 사실은 CLAUDE.md나 AGENTS.md에 두고 매 세션 읽는다. 반복되는 다단계 절차는 Skills에 두고 쓸 때만 본문을 로드한다. 릴리스 체크리스트를 전역 프롬프트에 넣으면 매 턴 설명서 값을 낸다.

Claude Code와 Codex가 같은 스킬을 공유할 수 있나?

SKILL.md 개방 형식은 공유한다. 경로와 호출은 공유하지 않는다. Claude Code는 .claude/skills/와 ~/.claude/skills/를, Codex는 .agents/skills/와 ~/.agents/skills/를 본다. 옛 ~/.codex/skills도 스캔된다. 교차 설치는 npx skills의 -a.

GitHub 인기 스킬을 원클릭으로 다 깔아야 하나?

안 된다. 넓은 description은 잘못된 작업에서 자동 발화한다. scripts/는 당신과 같은 권한으로 실행된다. SKILL.md와 스크립트를 읽은 뒤 프로젝트 디렉터리에 넣는다. 사용자 폴더에 넣어 모든 저장소로 새지 않게 한다.

Codex의 $skill-installer와 npx skills는 무엇이 다른가?

$skill-installer는 Codex 번들 설치기고 종종 ~/.codex/skills에 쓴다. npx skills는 교차 에이전트 패키지 관리자고 claude-code나 codex를 지정할 수 있다. 손수 만든 스킬은 .agents/skills 또는 .claude/skills에 둔다. 둘 다 본 뒤에 「안 깔렸다」고 판단한다.

스크립트 있는 Skills를 일상 노트북에서 돌려도 되나?

돌아간다. 낯선 저장소나 운영 비밀에서는 하지 마라. 먼저 컨테이너나 원격 Mac에서 트리거 범위와 쓰기 경계를 확인한 뒤 팀 저장소에 넣을지 정한다.

정리

2026년에 Agent Skills를 고를 때 커뮤니티 순위표를 장바구니로 쓰지 마라. 먼저 입구 세 종류로 골라라. 번들 스킬은 공식 후퇴, 프로젝트 스킬은 매주 반복하는 릴리스와 리뷰, 교차 규범은 읽은 것만. Claude Code와 Codex는 형식을 공유한다. 기본 디렉터리는 공유하지 않는다. 설명은 좁게, 스크립트는 나중에, 사용자 폴더는 예외이지 기본이 아니다. 분리, 트리거, 경로, 지울 수 있는 노드를 7단계 검수에 적어라. 원격 노드는 대여 페이지와 가격 페이지에서 보고, 계정 문제는 도움말 센터로 간다.

더 읽기

• Pi vs Claude Code vs Codex：2026 하니스 고르기 →
• Function Calling이란：OpenAI / Gemini / Claude →
• 자체 Agent Memory vs SaaS Memory →