지난 2년 동안 하나의 저장소 안에 코딩 에이전트별 지침 파일 3개가 서로 경쟁하듯 공존할 수 있었습니다. 에이전트마다 하나씩 있었고, 서로 공유되는 도구도 없었습니다. 이제 그런 파편화는 선택 사항이 됐습니다. 하나의 SKILL.md가 같은 폴더에서 Claude Code, Codex, Cursor를 모두 구동할 수 있습니다.
SKILL.md가 대체하는 것과 통합을 뒷받침하는 공개 표준
SKILL.md는 이전에 저장소를 파편화하던 에이전트별 지침 형식 3가지를 대체합니다. Claude Code용 CLAUDE.md, Codex용 AGENTS.md, Cursor용 .cursorrules가 그것입니다. 이 형식들은 공유 도구가 없었고 이식성도 전혀 없어서, 같은 지침을 세 번 작성하고 유지해야 했습니다. Agent Skills는 이를 필수 SKILL.md 파일을 중심으로 한 하나의 공개 형식으로 접어 넣습니다. 그래서 하나의 스킬 디렉터리를 표준을 따르는 모든 에이전트가 발견할 수 있습니다.
이 통합은 Anthropic의 MCP 전략을 따릅니다. Anthropic은 2025년 10월 16일 Claude 앱, Claude Code, Developer Platform API 전반에 Agent Skills를 출시했고 , 이후 2025년 12월 18일 agentskills.io에서 이 형식을 독립적인 공개 표준으로 발표했습니다. 이는 MCP가 2025년 12월 9일 Linux Foundation에 기증된 지 9일 뒤였습니다 .
도입 속도는 빨랐습니다. OpenAI와 Microsoft는 약 48시간 안에 지원을 추가했고, Codex는 2025년 12월 공식 SKILL.md 지원을 얻었습니다 . Cursor는 2026년 1월 22일 버전 2.4에서 뒤따랐고, SKILL.md 파일을 슬래시 명령 메뉴에서 발견하고 호출할 수 있게 했습니다 . 2026년 중반 기준으로 agentskills.io 쇼케이스에 올라온 약 40개 제품이 이 표준을 지원합니다. 여기에는 GitHub Copilot, VS Code, Gemini CLI, Goose, OpenCode가 포함되며, 거버넌스는 Linux Foundation의 Agentic AI Foundation 아래에 있습니다 .
이식 가능한 SKILL.md frontmatter와 선택 하위 디렉터리에 넣는 것
이식 가능한 SKILL.md에는 frontmatter 필드가 두 개만 필요합니다. name과 description입니다. 형식이 정의하는 나머지는 모두 선택 사항이고, 클라이언트별 설정은 모두 제외됩니다. name은 1~64자여야 하며, 소문자, 숫자, 하이픈만 사용할 수 있고, 부모 디렉터리 이름과 정확히 일치해야 합니다 . description은 1~1024자이며, 스킬이 무엇을 하는지와 언제 써야 하는지를 모두 밝혀야 합니다. 에이전트가 시작할 때 스킬을 활성화할지 판단하기 위해 읽는 트리거 매칭 텍스트가 바로 이것이기 때문입니다 .
선택 frontmatter에는 license, compatibility(최대 500자, git, jq, docker 같은 필수 CLI 등 환경 요구 사항용), metadata(작성자나 버전용 임의 key-value 맵), 그리고 실험적 필드인 allowed-tools가 추가됩니다. allowed-tools는 Bash(git:*) Bash(jq:*) Read처럼 공백으로 구분된 사전 승인 목록이며, 클라이언트마다 지원 여부가 다르므로 보장이 아니라 부가 기능으로 보는 편이 맞습니다 . 사양에서 특히 주의해야 할 경고도 있습니다. frontmatter에서는 XML 꺾쇠괄호를 피해야 합니다. 의도하지 않은 내용이 시스템 프롬프트에 주입될 수 있기 때문입니다 .
파일 외에도 스킬 디렉터리에는 세 가지 선택 하위 디렉터리를 둘 수 있습니다. 독립 실행형 Python, Bash, JS 실행 파일을 위한 scripts/, 필요할 때 불러오는 문서를 위한 references/, 템플릿, 스키마, 이미지를 위한 assets/입니다 . 이들은 시작 시점이 아니라 지침에서 호출할 때만 로드됩니다. 점진적 공개 방식에서는 에이전트가 시작할 때 name과 description만 로드하고(각각 약 100토큰), 활성화될 때 전체 본문을 읽으며, 참조 파일은 마지막에 불러옵니다 . SKILL.md는 500줄 이하, 대략 5,000토큰 이하로 유지하는 것이 좋습니다. Codex는 초기 스킬 목록을 컨텍스트 창의 2%(창 크기를 알 수 없으면 8,000자)로 제한하므로, 설명이 지나치게 길면 축약되고 대규모 스킬 세트에서는 항목이 통째로 누락될 수도 있습니다 .
아래 Python 스니펫은 실행 및 검증을 마친 예시로, 하나의 SKILL.md를 작성하고 기존 설정 파일 3개를 여기에 매핑해 통합이 어떻게 이뤄지는지 보여줍니다.
from pathlib import Path
skill = """# Codebase Skill
Use this single SKILL.md for agent instructions:
- project conventions
- commands to run
- review and safety rules
"""
old_files = ["CLAUDE.md", "AGENTS.md", ".cursorrules"]
Path("SKILL.md").write_text(skill)
print("One SKILL.md replaces scattered agent instruction files:")
for name in old_files:
print(f"- {name} -> SKILL.md")
print("\nSKILL.md:")
print(skill)표준 디렉터리, 심링크, 그리고 Claude Code, Codex, Cursor가 찾는 위치
스킬의 권위 있는 사본은 하나만 두고, 각 에이전트가 기대하는 위치에서 찾게 하세요. 원본은 .agents/skills/<name>/SKILL.md에 둡니다. 이 경로는 Codex의 네이티브 저장소 경로이자 더 넓은 생태계가 범용 프로젝트 위치로 안내하는 구조입니다 . Codex는 우선순위에 따라 스킬을 해석합니다. 먼저 저장소의 .agents/skills(현재 디렉터리에서 저장소 루트까지 거슬러 올라가며 검색), 그다음 사용자용 $HOME/.agents/skills, 관리자용 /etc/codex/skills, 마지막으로 번들된 시스템 스킬을 확인합니다 .
문제는 Claude Code가 .agents/skills를 스캔하지 않는다는 점입니다. Claude Code는 저장소의 .claude/skills/<name>/SKILL.md와 개인 스킬용 ~/.claude/skills/<name>/SKILL.md를 읽습니다 . Cursor는 더 좁습니다. 2026년 1월 22일에 출시된 Cursor 2.4에서 추가된 .cursor/skills/<name>/SKILL.md만 읽습니다 . 편집본을 세 벌 유지하는 대신, 두 클라이언트 경로를 모두 표준 디렉터리로 다시 심링크하세요.
| 에이전트 | 탐색 경로 | 매핑 |
|---|---|---|
| Codex | .agents/skills/<name>/ (+ $HOME, /etc/codex) | 표준 원본 |
| Claude Code | .claude/skills/<name>/ | 심링크 → .agents/skills/<name> |
| Cursor | .cursor/skills/<name>/ | 심링크 또는 미러링된 사본 |
수동으로 ln -s를 반복하지 않으려면 Vercel의 skills CLI를 쓰면 됩니다. 이 도구는 하나의 원본을 세 에이전트(claude-code, codex, cursor) 중 어디든 프로젝트 또는 전역 범위에 설치하며, 복사와 심링크 모드를 지원합니다. 예를 들어 skills install --agent claude-code --scope project --link처럼 실행할 수 있습니다 . 어디에 링크하기 전에 frontmatter를 검증하세요. skills-ref validate ./my-skill을 실행해 스펙 준수를 확인하고 , 이 명령을 CI lint에 연결해 기여자가 잘못 작성한 name이나 description이 미러링된 디렉터리들로 퍼지지 않게 하세요.
Cursor의 불일치 버그와 36% SKILL.md 출처 위험
심링크는 파일을 제자리에 매핑하지만, 에이전트가 실제로 그 파일을 읽는다고 보장하지는 않습니다. 2026년 5월 무렵 Cursor 사용자들은 .agents/skills 항목이 Settings와 slash-command 메뉴에는 표시되지만, 일부 빌드에서는 주입된 <available_skills> 프롬프트 컨텍스트에 전혀 나타나지 않는다고 보고했습니다. Cursor 직원은 이를 주입 단계 버그로 설명했고, 우회책으로 스킬 이름을 명시적으로 나열하는 rule을 제안했습니다 . 실무 원칙은 단순합니다. 심링크만으로 충분하다고 가정하지 마세요. 정확히 사용 중인 Cursor 버전에서 주입 동작을 확인하기 전까지는 .cursor/skills/ 미러를 유지하고, 채팅에서 /skill-name을 실행해 활성 컨텍스트에 들어오는지 확인하세요 .
더 날카로운 위험은 출처입니다. 스킬은 실행 가능한 scripts/를 포함할 수 있기 때문에, 2026년 감사에서는 테스트한 커뮤니티 SKILL.md 패키지 중 약 36%에서 프롬프트 인젝션 콘텐츠가 발견된 것으로 보고됐습니다 . 서드파티 스킬은 의존성처럼 다루세요. 실행하기 전에 전체 본문과 모든 스크립트를 읽고, 특정 커밋에 고정하며, skills-ref validate를 실행하세요 . 표준 관리자가 제시한 한 가지 관점처럼, "의존성을 다룰 때처럼 설치 전에 모든 스킬의 소스를 검토하세요" (source: agentskills.io).
마지막으로, 클라이언트별 추가 설정은 공유 파일 밖에 두세요. Claude Code의 동적 컨텍스트 주입 , allow_implicit_invocation: false 같은 Codex의 agents/openai.yaml 호출 정책 , Cursor의 hooks는 모두 에이전트별 wrapper 파일에 둬야 합니다. 이것들을 표준 SKILL.md에 섞어 넣는 순간, 다음 도구 업데이트에서 이식성은 조용히 무너집니다.
다음으로 해볼 일: 팀용 PR 리뷰나 changelog 스킬을 작성해 agentskills.io showcase에 게시하고, CI lint 단계에 skills-ref validate를 추가하세요. 검토를 거친 표준 준수 파일 하나를 만들고, 각 에이전트가 자기 위치에서 찾게 하면 됩니다.
자주 묻는 질문
SKILL.md는 추가 설정 없이 Claude Code, Codex, Cursor에서 함께 작동하나요?
자동으로 되지는 않습니다. 파일 형식, 즉 YAML 프런트매터와 Markdown 본문은 공유되지만 각 에이전트가 찾는 위치가 다릅니다. Claude Code는 .claude/skills/<name>/SKILL.md를 읽고, Codex는 현재 디렉터리부터 리포지터리 루트까지의 .agents/skills를 읽으며, Cursor는 .cursor/skills/를 읽습니다 . 세 도구 전체에 공통으로 적용되는 자동 탐색은 없습니다. 하나의 기준 소스(Codex의 .agents/skills/<name>가 일반적인 프로젝트 네이티브 경로)를 두고, 심볼릭 링크나 Vercel skills CLI를 사용하세요. 이 CLI는 프로젝트 또는 전역 범위에서 claude-code, codex, cursor에 설치해 모든 도구가 같은 단일 디렉터리를 바라보게 합니다 .
유효한 SKILL.md에 꼭 필요한 최소 항목은 무엇인가요?
프런트매터 필드 두 개입니다. 사양상 필수 항목은 name과 description뿐입니다. name은 1~64자, 소문자·숫자·하이픈으로 구성되어야 하며 부모 디렉터리 이름과 일치해야 합니다. description은 1~1024자로, 해당 스킬이 무엇을 하는지와 언제 사용하는지를 모두 설명해야 합니다 . 그 밖의 license, compatibility, metadata, 실험적 allowed-tools 목록, scripts/, references/, assets/ 하위 디렉터리는 모두 선택 사항입니다. 본문은 절차 중심으로 작성하고 대략 500줄, 5,000토큰 이하로 유지하며, 긴 자료는 참조 파일로 분리하세요 .
GitHub Copilot, Gemini CLI, VS Code도 SKILL.md를 지원하나요?
네. 2026년 중반 기준 agentskills.io 쇼케이스에는 약 40개 제품이 이 표준을 지원하는 것으로 올라와 있으며, Claude, Codex, Cursor뿐 아니라 GitHub Copilot, VS Code, Gemini CLI, Goose, OpenCode도 포함됩니다. 거버넌스는 Linux Foundation의 Agentic AI Foundation 아래에 있습니다 . 지원한다는 뜻은 각 클라이언트가 같은 공유 파일 형식을 읽는다는 의미입니다. 다만 탐색 경로와 호출 방식은 다를 수 있으므로, 설정 없이 이식된다고 가정하기 전에 각 도구 문서에서 기대하는 스킬 디렉터리를 확인하세요.
allowed-tools 필드로 스킬이 실행할 수 있는 작업을 안정적으로 제한할 수 있나요?
아니요. allowed-tools는 Bash(git:*) Bash(jq:*) Read처럼 공백으로 구분된 사전 승인 목록이지만 실험적 기능으로 표시되어 있으며, 클라이언트마다 지원 정도가 다릅니다 . Claude Code는 도구 사전 승인을 구현하지만, 다른 에이전트는 이 필드를 조용히 무시할 수 있습니다 . 보안 경계가 아니라 사용 힌트로 보고, 실제로 이를 존중하는 에이전트가 무엇인지 compatibility 필드에 문서화하세요.
커뮤니티에서 공개한 SKILL.md는 실행 전에 어떻게 평가해야 하나요?
스킬에는 실행 가능한 스크립트가 함께 들어 있을 수 있으므로 일반 의존성과 같은 방식으로 검토하세요. 2026년 감사에서는 테스트한 커뮤니티 스킬의 약 36%에서 프롬프트 인젝션 콘텐츠가 발견된 것으로 알려졌습니다 . 실행하기 전에 전체 SKILL.md 본문과 scripts/ 아래의 모든 파일을 읽고, 특정 커밋에 고정한 뒤 skills-ref validate ./my-skill로 프런트매터를 검증하세요 . 프런트매터의 XML 꺾쇠괄호도 주의해야 합니다. 사양에서는 이것이 시스템 프롬프트에 의도치 않은 지시를 주입할 수 있다고 경고합니다. 문서화되지 않은 네트워크 호출도 경계하세요.
이 글이 도움이 되셨다면, 새 글이 올라올 때마다 이메일로 받아보세요.
