Agent Skills

Agent Skills는 AI 에이전트에게 새로운 능력을 부여하는 오픈 포맷이다. Anthropic이 개발하고 오픈 표준으로 공개했으며, Claude Code, GitHub Copilot, Cursor, Gemini CLI, OpenCode, Junie, Amp, Goose 등 30개 이상의 에이전트 제품이 채택하고 있다. 에이전트는 갈수록 강력해지지만 실제 작업을 신뢰성 있게 수행하기 위한 컨텍스트가 부족한 경우가 많다. 스킬은 에이전트가 필요할 때 불러올 수 있는 절차적 지식과 팀·조직·사용자별 맥락을 제공해 이 문제를 해결한다.

스킬은 최소한 SKILL.md 파일 하나를 포함하는 디렉토리다. skill-name/ ├── SKILL.md # 필수: 메타데이터 + 지시문 ├── scripts/ # 선택: 실행 가능한 코드 ├── references/ # 선택: 추가 문서 └── assets/ # 선택: 템플릿, 리소스 SKILL.md 파일은 YAML 프론트매터와 마크다운 본문으로 구성된다.

프론트매터에 사용할 수 있는 필드: • name (필수) — 스킬 식별자. 소문자·숫자·하이픈만 허용, 1–64자. 디렉토리명과 일치해야 함 • description (필수) — 스킬이 무엇을 하는지, 언제 사용하는지 설명. 1–1024자. 에이전트가 이 필드를 보고 스킬 활성화 여부를 결정함 • license (선택) — 라이선스명 또는 번들 라이선스 파일 참조 • compatibility (선택) — 환경 요구사항. 의도한 제품, 시스템 패키지, 네트워크 접근 등. 1–500자 • metadata (선택) — 추가 메타데이터를 위한 키-값 맵 • allowed-tools (선택, 실험적) — 사전 승인된 도구 목록. 공백으로 구분 최소 예시: --- name: my-skill description: 무엇을 하는지, 언제 사용하는지 설명. ---

스킬은 3단계 점진적 공개 방식으로 동작해 컨텍스트를 효율적으로 관리한다. 1. Discovery — 에이전트 시작 시 모든 스킬의 name과 description만 로드(~100 토큰). 어떤 스킬이 있는지 파악하는 단계 2. Activation — 작업이 스킬 description과 매칭되면 SKILL.md 전체 본문을 컨텍스트에 로드. 5,000 토큰 이내 권장 3. Execution — 에이전트가 지시문을 따르며, 필요 시 scripts/, references/, assets/ 파일을 추가 로드 SKILL.md 본문은 500줄 이내로 유지하고, 상세 레퍼런스는 references/ 하위 파일로 분리하는 것을 권장한다.

프론트매터 이후 마크다운 본문에 실제 지시문을 작성한다. 형식 제한은 없으나 아래 항목을 포함하는 것을 권장한다. • 단계별 지시문 • 입력/출력 예시 • 자주 발생하는 엣지 케이스 에이전트가 스킬을 활성화하면 SKILL.md 전체를 한 번에 로드한다. 본문이 길어질 경우 references/ 디렉토리의 개별 파일로 분리하고 파일 참조를 사용한다.

• scripts/ — 에이전트가 실행할 수 있는 코드. Python, Bash, JavaScript 등 에이전트 구현에 따라 지원 언어가 다름. 독립적으로 동작하거나 의존성을 명확히 문서화해야 함 • references/ — 에이전트가 필요 시 읽는 추가 문서. REFERENCE.md, 도메인별 파일 등. 각 파일은 집중적으로 유지 — 에이전트가 온디맨드로 로드하므로 작을수록 좋음 • assets/ — 정적 리소스. 템플릿, 다이어그램, 데이터 파일 등

Agent Skills 포맷을 지원하는 주요 에이전트 및 도구: Claude Code, GitHub Copilot, VS Code, Cursor, Gemini CLI, OpenAI Codex, OpenCode, Junie (JetBrains), Amp, Goose, OpenHands, Roo Code, Letta, Firebender, Mux, Laravel Boost, Factory, Snowflake Cortex Code, Kiro, Spring AI, TRAE 등 30개 이상

skills-ref 라이브러리로 스킬의 유효성을 검사할 수 있다. skills-ref validate ./my-skill SKILL.md 프론트매터 유효성과 네이밍 컨벤션 준수 여부를 확인한다. GitHub: github.com/agentskills/agentskills