본문으로 건너뛰기

SKILL.md: 크로스 에이전트 오픈 표준

중급

수년 동안 모든 코딩 에이전트는 자기만의 파일을 가지고 있었습니다: .cursorrules, CLAUDE.md, Codex 시스템 프롬프트, Gemini instructions, 그리고 그 외 십수 개. 그러다 Anthropic이 조용히 내부 Skills 포맷을 오픈 스펙으로 전환했고 — 48시간 안에 세계 최대 규모의 에이전트들이 서로의 파일을 읽기 시작했습니다. 오늘날 SKILL.md가 들어 있는 code-reviewer/라는 하나의 디렉터리는 Claude Code, Codex CLI, ChatGPT, Gemini CLI, Junie, Kiro, Goose, Cursor에서 수정 없이 실행됩니다. 이는 에이전트 세계가 공유된 플러그에 가장 가깝게 다가간 지점입니다.

이 페이지는 실전 현장 가이드입니다: 이 표준이 바이트 레벨에서 실제로 무엇인지, 100개 스킬 설치를 저렴하게 만드는 한 가지 영리한 기법(점진적 공개), 손대는 순간 이식성을 깨뜨리는 정확한 필드들, 정직한 보안 관점, 그리고 오늘 바로 배포할 수 있는 복사-붙여넣기 가능한 이식 가능한 스킬.

What you'll learn
  • 파일 포맷 수준에서 SKILL.md가 무엇인지 이해하기 — 필수 필드, 선택 필드, 디렉터리 레이아웃
  • 점진적 공개 이해하기: 왜 100개 스킬이 시작 시 본문의 100배가 아니라 ~10K 토큰밖에 들지 않는지
  • 에이전트 간 이식성을 조용히 깨뜨리는 정확한 벤더 확장을 알기
  • Claude Code, Codex CLI, Gemini CLI에서 수정 없이 실행되는 스킬 작성하기
  • 마켓플레이스에서 스킬을 설치하기 전에 보안 트레이드오프를 정직하게 저울질하기

표준이 실제로 무엇인가​

마케팅을 걷어내고 나면 Agent Skills 오픈 표준은 머릿속에 담을 수 있을 만큼 작습니다:

  • 디렉터리 — 그 이름이 스킬의 name이 됨
  • 필수 SKILL.md 파일 — 안에 YAML 프론트매터, 그다음 Markdown 본문
  • 선택적 형제 항목들: scripts/(스킬이 실행할 수 있는 실행 파일), references/(스킬이 필요할 때 불러올 수 있는 문서), assets/(템플릿, 이미지, 프롬프트 파일), 그리고 나중에 추가된 — 옵트인 방식의 벤더별 설정을 위한 agents/

이것이 전체 표면적입니다. 두 개의 필수 프론트매터 필드가 대부분의 일을 합니다:

  • name — 최대 64자, lowercase-with-hyphens, 부모 디렉터리와 일치해야 함
  • description — 최대 1,024자, 에이전트가 현재 작업을 위해 이 스킬을 로드할지 여부를 결정할 때 사용하는 문장

그 외의 모든 것 — license, compatibility, metadata, 그리고 여전히 실험적인 allowed-tools — 은 선택 사항이며, 이해하지 못하는 도구들은 안전하게 무시합니다. 본문은 Markdown이며, 커뮤니티 관행은 ~5,000 토큰 이하로 유지하는 것이고, 실제 스킬들은 대체로 이를 지킵니다: 가장 큰 마켓플레이스의 스킬 중간값 크기는 약 1,414 토큰이며 90%가 3,935 토큰 미만입니다.

한 가지 영리한 기법: 점진적 공개​

SKILL.md가 대규모로 동작하는 이유는 파일 포맷이 아니라 — 에이전트가 그것을 어떻게 로드하는지 입니다. 표준을 준수하는 모든 에이전트는 세 개의 계층을 구현합니다:

Guided walkthrough1 of 3
  1. 에이전트가 skills 디렉터리를 순회하며 모든 SKILL.md의 프론트매터만 읽습니다. 스킬당 대략 100 토큰입니다. 100개 스킬을 설치하면 첫 프롬프트 전에 ~10K 토큰의 컨텍스트를 소비한 셈 — 긴 시스템 메시지 하나보다 저렴합니다.

이것이 스펙이 description을 그렇게 엄격히 제한하고 일급 필드로 취급하는 이유입니다: 스킬을 활성화할지 선택할 때 모델이 보는 유일한 텍스트이기 때문입니다. 애매한 description은 "동작해야 마땅한" 스킬이 절대 발화되지 않는 가장 흔한 단일 원인입니다.

:::tip Description은 마지막에 쓰고, 다시 쓰기 스킬의 본문이 탄탄해지면, 돌아가서 description을 광고 카피처럼 다뤄야 합니다. 그 역할은 하나뿐입니다: 이 스킬이 담당해야 할 작업의 형태를 모델이 인지하도록 돕는 것. "Reviews pull requests"는 나쁩니다. "Reviews a PR diff for logic bugs, missing tests, and violated project conventions; use whenever the user asks for a review, code review, or 'look at this PR'"는 좋습니다. :::

범용 디렉터리​

표준을 준수하는 모든 에이전트는 동일한 레이아웃을 기대합니다. 이것은 어디서나 동작합니다:

code-reviewer/
├── SKILL.md          # required — the instructions the agent reads
├── scripts/          # optional — executables the skill can invoke
│   └── run-linters.sh
├── references/       # optional — long docs the skill pulls on demand
│   └── style-guide.md
├── assets/           # optional — templates, prompt files, snippets
│   └── pr-comment-template.md
└── agents/           # optional — VENDOR-SPECIFIC, opt-in only
    └── openai.yaml   # ignored by every non-Codex agent

agents/ 하위 디렉터리는 표준의 안전밸브입니다: 벤더가 이식 가능한 핵심을 오염시키지 않고 확장 기능을 배포할 수 있게 합니다. agents/openai.yaml에 있는 파일은 Codex 전용이며 그 외 모든 에이전트는 그냥 무시합니다. 추가적인 힘이 필요할 때 사용하되, 이식성을 대가로 지불한다는 점을 인지하세요.

실제로 이식되는 것 vs 조용히 이식되지 않는 것​

전체 스펙은 이식성을 위해 설계되었지만, 실제 스킬들은 세 가지 실패 모드를 가지고 있습니다.

사용하는 것이식 가능?이유
name, description, Markdown 본문✅ 예핵심 스펙. 모든 준수 에이전트가 동일하게 읽습니다.
본문에서 참조되는 scripts/, references/, assets/✅ 예디렉터리 레이아웃은 스펙의 일부입니다. 본문이 지시하면 에이전트가 읽습니다.
license, metadata✅ 예 (안전하게 무시됨)선택 필드 — 지원하지 않는 에이전트는 오류 없이 건너뜁니다.
allowed-tools 프론트매터⚠️ 부분적스펙에서 실험적으로 표시됨. 에이전트별 문법이 표준화되지 않았습니다. Claude Code는 한 형식을, Codex CLI는 다른 형식을 존중하며, 대부분의 다른 에이전트는 완전히 무시합니다.
Claude Code의 when_to_use 리스트❌ Claude 전용Codex, Gemini CLI, 그리고 그 외 모두가 조용히 무시합니다.
Claude Code의 context: fork 서브에이전트 플래그❌ Claude 전용비이식 서브에이전트 실행 시맨틱스 — 모델 동작이 다른 곳에서는 다릅니다.
agents/openai.yaml 확장❌ Codex 전용설계상 명시적으로 벤더 범위. 다른 에이전트가 무시하기 때문에 이식 가능.

교훈은 단호합니다: name + description + Markdown 본문 + 세 개의 선택적 하위 디렉터리에 머무르면 스킬은 어디서나 실행됩니다. 핵심 두 개를 넘어 어떤 프론트매터 필드로든 손을 뻗으면 하나의 에이전트를 위해 짓는 것입니다. 이는 정당한 선택이지만 — 어떤 스킬은 진정으로 그것이 필요합니다 — 템플릿을 복사-붙여넣기 했기 때문이 아니라 의도적으로 하세요.

활성화가 실제로 어떻게 작동하는가 (에이전트별)​

스펙은 파일을 표준화하지, 결정을 표준화하지 않습니다. 각 에이전트는 여전히 시작 시점에 읽은 description들에 대해 자체 활성화 로직을 실행합니다:

  • Claude Code는 모델의 현재 턴 판독을 description과 (있을 경우) Claude 전용 when_to_use 리스트에 대조합니다; 활성화는 키워드 규칙이 아니라 모델의 결정입니다.
  • Codex CLI는 동일한 description 기반 활성화를 사용하며, agents/openai.yaml에서 선택적으로 오버라이드할 수 있습니다.
  • Gemini CLI도 마찬가지로 시작 시 description을 로드하고 Gemini가 선택하게 합니다; 동작은 Gemini 자체의 도구 선택 휴리스틱을 따릅니다.
  • Cursor, Junie, Kiro, Goose는 모두 가중치의 경미한 차이와 함께 description 기반 활성화를 구현합니다.

실제적 함의: 한 에이전트에서는 절대 발화되지 않는데 다른 에이전트에서는 작동하는 스킬은 거의 항상 본문 문제가 아니라 description 문제입니다. description을 스킬의 내부가 아닌 사용자 요청의 형태를 묘사하도록 다시 쓰면, 모든 에이전트에서 동시에 발화율이 올라갑니다.

복사해서 쓸 수 있는 이식 가능한 SKILL.md​

여기 최소한이면서 실제로 이식 가능한 code-review 스킬이 있습니다. ~/.agents/skills/code-reviewer/SKILL.md에 넣으면 수정 없이 Claude Code, Codex CLI, ChatGPT, Gemini CLI에서 실행됩니다.

code-reviewer/SKILL.md

---
name: code-reviewer
description: Reviews a diff or pull request for logic bugs, security issues, missing tests, and violations of project conventions. Use whenever the user asks for a review, code review, PR review, or "look at this diff / patch / change".
license: MIT
---

# Code Reviewer

You review code changes with the discipline of a staff engineer who cares
about the codebase surviving contact with reality. You are opinionated but
short. You never restate what the diff does — the user can read it.

## What to look at

1. **Logic bugs** — off-by-one, wrong operator, swapped arguments, unhandled
 error path, race, silent catch.
2. **Missing tests** — any changed behavior without a test is a finding.
3. **Security** — injection, secrets, missing auth checks, unsafe deserialization,
 unbounded input.
4. **Project conventions** — if a CLAUDE.md, AGENTS.md, .cursorrules, or README
 exists in the repo root, load it and enforce what it says.
5. **Complexity that will hurt future readers** — call it out, propose the
 simpler shape.

## What NOT to do

- Do not comment on formatting the linter will catch.
- Do not praise. No "great work" / "nice refactor".
- Do not summarize the diff. Assume the reader read it.

## Output format

For each finding, one line:

`path:line — <severity>: <problem>. <concrete fix>.`

Severities: 🔴 blocker, 🟠 important, 🟡 nit.

End with a one-line verdict: "ship", "ship with fixes", or "rework".

그 스킬의 모든 줄은 모든 준수 에이전트에서 실행됩니다. 프론트매터에 벤더 범위인 것은 하나도 없습니다. 본문은 어떤 에이전트든 파싱하는 평범한 Markdown 헤딩을 사용합니다.

이제 비이식적인 변형과 비교해 봅시다 — 미묘하지만 Claude 전용입니다:

Claude-only variant (do not use if you want portability)

---
name: code-reviewer
description: Reviews a diff or pull request.
when_to_use:
- user asks for a review
- user pastes a diff
context: fork
allowed-tools: [Bash, Read, Grep]
---

세 가지가 동시에 이식성을 깨뜨립니다: when_to_use(Claude Code 전용), context: fork(Claude Code 서브에이전트 시맨틱스), 그리고 allowed-tools(실험적이며 일관되게 존중되지 않음). Codex는 description을 "Reviews a diff or pull request"로 읽을 것이고 — 너무 애매해서 거의 활성화되지 않을 것 — 나머지는 무시할 것입니다.

보안 관점 (자신에게 정직하기)​

어떤 마켓플레이스에서든 스킬을 설치할 때의 불편한 진실: 스킬은 당신의 환경에서 당신의 권한으로 실행되는 매우 유능한 에이전트에게 주어지는 임의의 지침입니다. 표준은 코드 서명, 샌드박싱, 필수 검토, 런타임 권한 모델 어느 것도 명시하지 않습니다. 설계상 그것은 텍스트 파일 스펙이지 보안 스펙이 아닙니다.

구체적 수치는 대규모 공개 스킬 카탈로그에 대한 독립적 분석에서 (인용 전 원본 확인):

  • 공개적으로 공유된 스킬 중 대략 3분의 1이 최소한 하나의 보안 관련 결함을 포함합니다 — 지나치게 광범위한 셸 명령, 하드코딩된 시크릿, 신뢰할 수 없는 URL 호출, 또는 curl | sh 스타일 부트스트랩 단계.
  • 더 작지만 0은 아닌 세트의 스킬들이 명백히 악의적이라고 지목되었습니다 — 유출, 자격 증명 수집, 파괴적 작업 시도.
  • 스킬은 에이전트가 상속받는 것을 그대로 상속받습니다. 에이전트가 ~/.ssh/를 읽을 수 있다면, 설치한 어떤 스킬도 그럴 수 있습니다.

실제로 작동하는 방어책:

Guided walkthrough1 of 4
  1. Markdown입니다. 1분이면 됩니다. description이 'formats prose'라고 하는데 본문에 알지 못하는 URL로의 `curl`이 포함되어 있다면, 그 순간이 멈춰야 할 때입니다.

스킬이 어떻게 침해되는지와 무엇을 확인해야 하는지에 대한 더 깊은 논의는 Agent Skills 심사와 공격받는 코딩 에이전트를 참조하세요.

스킬을 작성해야 할 때 vs 단지 프롬프트할 때​

스킬 카탈로그의 새 관리자들은 종종 그것들을 과잉 생산합니다. 유용한 규칙:

  • 일회성 작업이나 한 프로젝트에서만 쓸 형태에는 프롬프트를 사용하세요. 스킬은 시작 비용을 수반하며 — 작더라도 — description 예산을 어지럽힙니다.
  • 동일한 지침이 여러 채팅이나 프로젝트에 걸쳐 적용되는 경우(코드 리뷰, 커밋 메시지 작성, 체인지로그 생성, 인보이스 추출) 그리고 description이 명확할 수 있을 때 스킬을 작성하세요. 명료한 description을 쓸 수 없다면 어차피 스킬은 안정적으로 발화되지 않습니다.
  • 작업이 자체 도구 세트, 자체 모델 선택, 또는 진정한 병렬성을 필요로 할 때는 대신 서브에이전트를 사용하세요. 스킬은 메인 모델에게 지시합니다; 서브에이전트는 별도로 실행됩니다. 서브에이전트를 참조하세요.

관련 읽을거리​

이해도 점검​

Check yourself

0/4
  1. 100개 스킬을 설치합니다. 시작 시점에 description들이 에이전트에게 드는 토큰 비용은 대략 얼마입니까?
  2. 다음 프론트매터 필드 중 Claude Code에서는 작동하지만 Codex CLI와 Gemini CLI에서는 조용히 스킬을 깨뜨리는 것은 무엇입니까?
  3. 당신이 작성한 스킬이 Claude Code에서는 안정적으로 발화되지만 Codex CLI에서는 거의 발화되지 않습니다. 가장 지렛대가 큰 첫 수정 사항은 무엇입니까?
  4. Agent Skills의 보안 자세가 예를 들어 잠금파일과 감사 도구를 갖춘 npm 패키지보다 근본적으로 더 취약한 이유는 무엇입니까?

출처 및 더 읽을거리​