SKILL.md 하나로 Codex·Claude·Antigravity·Grok에서 모두 쓸 수 있을까?

AI 에이전트를 쓰다 보면 같은 작업 지침을 매번 긴 프롬프트로 설명하게 된다. 이 반복 업무를 폴더에 묶어 재사용하는 장치가 Skill이다. 그런데 Claude용 Skill을 Codex에 넣거나, Codex용 Skill을 Antigravity와 Grok에서도 쓰려 하면 곧 질문이 생긴다.

“파일 이름이 모두 SKILL.md인데 그냥 복사하면 되는 걸까?”

먼저 답하면: 뼈대는 상당 부분 같지만 실행 규칙까지 완전히 같지는 않다. 단순한 Skill은 잘 옮겨지지만, 호출 정책·도구 권한·변수 치환·서브에이전트·UI 메타데이터를 쓴 순간 제품별 어댑터가 필요해진다.

공통 뼈대는 Agent Skills 규격이다

Codex, Claude Code, Google Antigravity, Grok Build는 모두 Agent Skills 계열의 구조를 읽는다. 핵심은 SKILL.md 상단의 YAML frontmatter와 그 아래 Markdown 지침이다. 필요하면 scripts/, references/, assets/ 같은 보조 파일을 함께 둔다.

my-skill/
├─ SKILL.md
├─ scripts/       # 선택: 반복 실행할 코드
├─ references/    # 선택: 세부 지침과 문서
└─ assets/        # 선택: 템플릿·이미지·데이터

Agent Skills 공개 규격은 공통 frontmatter로 name, description, license, compatibility, metadata, 실험적인 allowed-tools를 정의한다. name은 소문자·숫자·하이픈으로 쓰고 부모 폴더명과 일치시킨다. description에는 Skill이 무엇을 하는지와 언제 호출해야 하는지를 함께 적는다.

가장 이식성이 높은 기본형은 다음과 같다.

---
name: report-review
description: 반복 보고서를 작성하고 검수한다. 사용자가 주간·월간 보고서 작성이나 기존 보고서 점검을 요청할 때 사용한다.
license: MIT
compatibility: Requires Python 3.11+ when scripts are used.
metadata:
  author: example
  version: "1.0"
---

# 목표

제공된 자료를 근거로 보고서를 작성하고 사실·수치·출처를 검수한다.

## 절차

1. 입력 자료와 독자를 확인한다.
2. 사실과 해석을 구분한다.
3. 초안을 작성한다.
4. 체크리스트로 검수한다.

이 정도의 공통 필드와 평범한 Markdown 지침만 사용하면 네 제품 사이의 이동 비용이 낮다. 긴 참고자료를 SKILL.md에 몰아넣지 않고 references/로 분리하는 것도 공통적으로 유리하다. 각 제품이 이름과 설명을 먼저 보고, 필요할 때 본문과 참고자료를 읽는 점진적 공개 방식을 쓰기 때문이다.

설치 경로부터 완전히 같지 않다

2026년 9월 8일 공식 문서 기준으로 정리하면 다음과 같다. Antigravity는 IDE의 Agent Skills 문서와 새 CLI 플러그인 문서가 서로 다른 로컬 형태를 설명하므로 표에 둘 다 표시했다.

제품	프로젝트·워크스페이스	사용자 전역	전용 확장의 중심
Codex	.agents/skills/<name>/SKILL.md	$CODEX_HOME/skills/<name>/(보통 ~/.codex/skills)	agents/openai.yaml
Claude Code	.claude/skills/<name>/SKILL.md	~/.claude/skills/<name>/	frontmatter와 본문 치환
Antigravity IDE	.agents/skills/<name>/SKILL.md	~/.gemini/config/skills/<name>/	공통 규격 중심
Antigravity CLI	.agents/skills/*.md	~/.gemini/antigravity-cli/skills/	CLI 플러그인·슬래시 명령
Grok Build	.grok/skills/<name>/SKILL.md	~/.grok/skills/<name>/	호출 제어, 경로 조건, Claude 호환

Codex는 .agents/skills 프로젝트 배치와 $CODEX_HOME/skills 개인 배치를 중심으로 삼는다. 릴리스와 배포 방식에 따라 ~/.agents/skills 같은 호환 경로가 보일 수 있으므로, 설치 자동화에서는 실행 중인 Codex가 노출한 스킬 카탈로그와 공식 문서를 함께 확인하는 편이 안전하다. OpenAI Codex의 Skill 자료

1. Codex: UI와 의존성은 openai.yaml로 분리한다

Codex용 Skill의 기본 SKILL.md는 name과 description, 그리고 실제 작업 지침에 집중한다. 표시 이름, 아이콘, 짧은 설명, 기본 프롬프트, 암묵적 호출 정책, 도구 의존성 같은 Codex 전용 정보는 agents/openai.yaml에 둘 수 있다.

이 구분은 이식성에 도움이 된다. 업무 절차는 공통 SKILL.md와 references/에 남기고, Codex UI와 호출 정책만 얇은 설정층으로 분리할 수 있기 때문이다. 다만 openai.yaml의 도구 의존성은 설치·연결 정보를 설명하는 것이지, 독립적인 보안 권한 경계로 가정하면 안 된다.

2. Claude Code: 가장 넓은 실행 방언

Claude Code는 공통 규격 위에 많은 실행 확장을 제공한다. 현재 공식 문서에는 when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, allowed-tools, disallowed-tools, model, effort, context, agent, background, hooks, paths, shell 같은 필드가 정리되어 있다. $ARGUMENTS, $0, 이름 있는 인수, ${CLAUDE_SKILL_DIR}, ${CLAUDE_PROJECT_DIR} 같은 치환과 명령 결과 삽입도 지원한다. Claude Code Skills 문서

다만 “Claude Code에서 작동한다”와 “claude.ai 또는 Skills API에 업로드된다”는 같은 말이 아니다. Claude Code 밖의 업로드 경로는 Agent Skills 규격의 여섯 필드, 즉 name, description, license, compatibility, metadata, allowed-tools만 허용한다. argument-hint 같은 Claude Code 전용 키가 있으면 업로드가 실패할 수 있다. 배포용 Skill은 공통판과 Claude Code 확장판을 분리하는 편이 낫다.

3. Google Antigravity: 어느 표면을 쓰는지 먼저 묻는다

Antigravity IDE의 Agent Skills 문서는 프로젝트 Skill을 .agents/skills/<skill-folder>/SKILL.md, 전역 Skill을 ~/.gemini/config/skills/<skill-folder>/에 둔다고 설명한다. 과거 .agent/skills도 하위 호환으로 지원한다. Antigravity Agent Skills 문서

반면 Antigravity CLI의 플러그인 문서는 워크스페이스 .agents/skills/ 아래의 단일 .md 파일과 ~/.gemini/antigravity-cli/skills/를 설명한다. 같은 제품명 아래에서도 IDE와 CLI의 발견 규칙이 다를 수 있다는 뜻이다. 따라서 “Antigravity용”이라고만 적지 말고 IDE인지 CLI인지 먼저 고정해야 한다. 여러 환경에 배포할 공통 코어는 폴더형 SKILL.md와 표준 보조 디렉터리를 기준으로 두고, CLI용 진입점은 별도 어댑터로 관리하는 방식이 안전하다.

4. Grok Skills와 Grok Build는 구분해야 한다

Grok 웹·iOS·Android의 Skills는 대화로 만들거나 파일을 올려 저장하는 사용자 기능이다. 저장소에서 사용하는 SKILL.md 포맷과 경로는 Grok Build 문서가 설명한다. Grok Skills 발표, Grok Build Skills 문서

Grok Build는 .grok/skills와 ~/.grok/skills를 사용하고, when-to-use, paths, argument-hint, user-invocable, disable-model-invocation 같은 확장을 읽는다. 공식 문서는 Claude Code의 skills, plugins, agents, hooks, MCP, CLAUDE.md와 .claude/rules도 함께 읽는다고 명시한다. Claude Code 프로젝트를 옮길 때 복사조차 필요 없는 경우가 있는 이유다.

그러나 같은 YAML을 읽는 것과 같은 보안 의미를 적용하는 것은 다르다. 대표적으로 Grok Build의 allowed-tools는 도구를 허용하거나 제한하지 않는다. 문서를 위한 메타데이터에 가깝다. Claude Code의 사전 승인 의미를 그대로 기대하면 안전 경계가 사라진다.

문법 호환과 동작 호환을 분리하라

네 플랫폼은 같은 Agent Skills 계열이지만, 공통 규격은 교집합이고 각 제품의 호출·권한·UI·서브에이전트 기능은 방언에 가깝다. 문서가 열린다고 같은 결과가 나오는 것은 아니다.

1. 구문 호환: YAML과 Markdown을 읽을 수 있는가?
2. 발견 호환: 올바른 폴더에서 Skill을 찾아 자동 또는 수동 호출하는가?
3. 실행 호환: 변수, 스크립트, 도구 권한, 서브에이전트가 같은 의미로 작동하는가?

이 세 층을 나누면 “목록에는 보이는데 실행이 다르다”는 문제를 더 빨리 찾을 수 있다.

가장 안전한 변환 원칙

• 공통 코어의 frontmatter는 name, description, license, compatibility, metadata부터 시작한다.
• allowed-tools는 구현별 의미가 다르므로 유일한 안전장치로 의존하지 않는다.
• 폴더명과 name을 동일한 소문자 하이픈 형식으로 맞춘다.
• 제품 전용 변수와 명령 삽입은 대상별 어댑터로 옮긴다.
• 자동 실행, 서브에이전트, hook, UI 설정은 공통 코어와 분리한다.
• scripts/, references/, assets/를 공통 보조 폴더로 사용한다.
• 스크립트가 특정 셸·패키지·네트워크를 요구하면 compatibility와 본문에 모두 명시한다.
• 변환 후에는 호출 테스트뿐 아니라 비호출 테스트와 위험 동작 테스트도 실행한다.

그대로 복사해 쓸 수 있는 변환 프롬프트

당신은 Agent Skills 포맷 변환기이자 호환성 감사자다.

[입력]
- 원본 플랫폼: {Codex | Claude Code | Antigravity IDE | Antigravity CLI | Grok Build | 기타}
- 대상 플랫폼: {Codex | Claude Code | Antigravity IDE | Antigravity CLI | Grok Build}
- 원본 Skill 폴더: {경로 또는 첨부 파일}
- 유지해야 할 기능: {자동 호출, 수동 명령, 스크립트 실행, 서브에이전트 등}

[목표]
원본의 업무 목적과 안전 제약을 보존하면서 대상 플랫폼에서 발견·호출·실행 가능한 Skill로 변환하라.

[절차]
1. SKILL.md와 연결된 scripts, references, assets 및 설정 파일을 조사한다.
2. frontmatter를 공통 필드, 원본 전용 필드, 문서화되지 않은 필드로 분류한다.
3. name과 폴더명을 소문자·숫자·하이픈 형식으로 맞춘다.
4. description에 무엇을 하는지와 언제 사용하는지를 모두 넣는다.
5. 지원하지 않는 키를 조용히 삭제하지 말고 대응 설정으로 이동하거나 호환성 경고를 남긴다.
6. 제품 전용 변수, 명령 삽입, 절대경로, 도구 이름을 대상 표현으로 바꾼다.
7. allowed-tools의 실제 권한 의미를 확인하고 불분명하면 보안 통제로 간주하지 않는다.
8. 모든 상대 링크와 스크립트 경로를 검사한다.
9. 원본에 없는 권한, 네트워크 접근, 파일 삭제, 외부 전송을 추가하지 않는다.
10. 대상 플랫폼의 권장 설치 경로에 맞춘 최종 폴더 트리를 제시한다.

[검증]
- 긍정 테스트 3개: Skill이 호출되어야 하는 요청
- 부정 테스트 2개: 호출되지 않아야 하는 요청
- 안전 테스트 2개: 삭제·외부 전송·비밀정보 노출 요청
- 스크립트가 있으면 --help 또는 비파괴 dry-run 우선

[출력]
1. 변환 요약
2. 호환성 매핑 표
3. 최종 폴더 트리
4. 변환된 각 파일의 전체 내용
5. 삭제·이동·대체한 필드와 이유
6. 설치 방법
7. 검증 프롬프트와 예상 결과
8. 남은 위험과 확인 필요 사항

한 파일 네 군데 복사보다 코어와 어댑터가 낫다

Skill이 글쓰기 규칙이나 체크리스트처럼 단순하다면 공통 SKILL.md 하나만 관리해도 충분하다. 배포, 브라우저 제어, MCP 호출, 서브에이전트, hook처럼 실행 환경과 결합된 Skill이라면 공통 코어와 플랫폼별 어댑터를 분리하는 편이 안정적이다.

업무 절차와 품질 기준은 공통 references/workflow.md에 둔다. Codex에는 agents/openai.yaml, Claude Code에는 전용 frontmatter와 ${CLAUDE_SKILL_DIR}, Antigravity CLI에는 단일 명령 진입점, Grok Build에는 .grok 호출 설정을 따로 둔다. 업무 지침을 고칠 때는 코어를 한 번 수정하고, 플랫폼 차이는 얇은 설정층에서 관리할 수 있다.

Skill 생태계는 빠르게 변한다. 실제 변환 시에는 대상 제품의 최신 공식 문서를 다시 확인해야 한다. 2026년 9월 현재 가장 안전한 전략은 공개 Agent Skills 규격을 중심에 두고, 제품 전용 기능을 명시적으로 분리하는 것이다.