Agent Skills 완전 정리 — 공개 사양부터 SKILL.md 실무 설계, skills.sh 보안까지

AI 에이전트를 사용하다 보면 ‘스킬’, ‘Agent Skills’, ‘skills.sh’, ‘MCP’, ‘시스템 프롬프트’라는 표현이 한꺼번에 등장합니다. 이름이 비슷해 같은 기관이나 제품처럼 보이지만 각각의 역할은 다릅니다.

 

가장 먼저 바로잡아야 할 점은 Agent Skills가 기관명이 아니라는 것입니다. AI 에이전트에 특정 업무 절차와 참고자료, 실행 코드를 패키지로 추가하기 위한 공개 파일 형식의 이름입니다. Anthropic이 처음 개발해 공개했고, 현재 Claude뿐 아니라 ChatGPT와 Codex 등 여러 에이전트 제품이 이 형식을 지원합니다.

 

그렇다고 ISO, IEC, IETF, W3C 같은 표준화 기구가 제정한 국제표준은 아닙니다. 정확히는 여러 구현체가 채택하는 공개 상호운용 포맷 또는 오픈 사양에 가깝습니다.

 

이 글에서는 세 가지를 구분해 설명합니다.

1. Agent Skills 공개 사양이 실제로 정의하는 것
2. 보안·감사 업무용 스킬을 안정적으로 만드는 실무 설계
3. 공개 스킬을 검색·설치하는 skills.sh와 공급망 보안

Agent Skills는 누가 만들었나?

Agent Skills 공식 문서는 이 형식이 Anthropic에서 처음 개발됐고, 오픈 형식으로 공개된 뒤 여러 에이전트 제품이 채택했다고 설명합니다. 공통 사양과 문서는 agentskills/agentskills 저장소에서 공개 개발되고 있습니다.

 

관계를 단순화하면 다음과 같습니다.

Anthropic
└── Agent Skills 형식 최초 개발·공개

Agent Skills 공개 사양
├── agentskills.io 문서
├── agentskills/agentskills 사양 저장소
├── Claude의 스킬 구현
├── ChatGPT·Codex의 스킬 구현
└── 기타 호환 에이전트 구현

Anthropic의 skills 저장소는 현재 Claude에서 사용하는 구현과 예제 중심입니다. 저장소 자체도 공통 표준에 관한 정보는 agentskills.io를 보라고 구분합니다.

 

OpenAI 역시 독자적인 동일 명칭 규격을 새로 만든 것이 아닙니다. OpenAI의 스킬 문서는 ChatGPT와 Codex의 스킬이 공개 Agent Skills 사양을 기반으로 한다고 명시합니다.

 

따라서 다음 문장이 가장 정확합니다.

Agent Skills는 Anthropic이 처음 개발해 공개한 AI 에이전트용 경량 스킬 패키지 형식이며, 현재 여러 제품이 채택하는 공개 상호운용 사양이다.

그림: Agent Skills 사양과 각 제품 구현, skills.sh의 역할 관계 · Agent Skills Overview, OpenAI Build skills, skills.sh Documentation을 바탕으로 재구성

Agent Skills 사양이 정의하는 최소 구조

스킬의 핵심은 디렉터리 하나와 그 안의 SKILL.md입니다.

aws-iam-policy-review/
├── SKILL.md              # 필수
├── scripts/              # 선택: 실행 코드
├── references/           # 선택: 정책·문서·지식
├── assets/               # 선택: 템플릿·샘플
└── 그 밖의 파일          # 필요에 따라 추가 가능

SKILL.md는 YAML Frontmatter와 Markdown 본문으로 구성합니다.

---
name: aws-iam-policy-review
description: >
  Review AWS IAM policies for excessive permissions, privilege escalation,
  unsafe trust relationships, and missing conditions.
  Use when a user asks to assess or harden an IAM policy.
---

# AWS IAM Policy Review

1. 정책 문법을 확인한다.
2. Action, Resource, Principal, Condition을 분석한다.
3. 권한 상승 가능성을 분석한다.
4. 근거와 최소 권한 수정안을 제안한다.

Agent Skills 공식 사양이 요구하는 Frontmatter 필드는 사실상 name과 description 두 개입니다.

필드	필수 여부	주요 제한	용도
name	필수	1~64자, 영문 소문자·숫자·하이픈, 디렉터리명과 일치	스킬 식별
description	필수	1~1,024자	무엇을 하며 언제 사용하는지 설명
license	선택	라이선스명 또는 파일 참조	배포·사용 조건
compatibility	선택	1~500자	실행 환경, 패키지, 네트워크 요구사항
metadata	선택	문자열 키-값	작성자·버전 등 확장 정보
allowed-tools	선택	구현체별 지원 차이	사전 허용 도구, 실험적 기능

allowed-tools가 사양에 있다고 해서 모든 에이전트가 똑같이 해석한다고 가정하면 안 됩니다. 이 필드는 실험적이며 구현체별 지원과 권한 모델을 별도로 확인해야 합니다.

에이전트는 스킬을 어떻게 발견하는가?

Agent Skills의 중요한 설계 원리는 점진적 공개(Progressive Disclosure)입니다.

1. Discovery
   모든 스킬의 name과 description만 확인

2. Activation
   사용자 요청과 맞는 스킬의 SKILL.md 전체 로드

3. Execution
   필요한 scripts·references·assets만 추가 사용

에이전트가 처음부터 모든 스킬의 긴 본문을 읽으면 컨텍스트가 빠르게 소모됩니다. 그래서 description은 단순 소개가 아니라 스킬 라우팅 규칙처럼 작성해야 합니다.

 

좋은 설명에는 다음 세 가지가 들어갑니다.

무엇을 수행하는가
+ 언제 호출해야 하는가
+ 비슷해 보이지만 호출하지 말아야 할 경우

예를 들어 “AWS를 도와준다”보다는 “IAM 정책의 과도한 권한과 권한 상승을 검토하며, 일반적인 AWS 비용·네트워크 검토에는 사용하지 않는다”가 훨씬 정확한 트리거가 됩니다.

 

공식 사양은 전체 SKILL.md를 500줄, 약 5,000토큰 이하로 유지하고 긴 자료는 별도 파일로 분리하는 방식을 권장합니다. 이는 강제 제한이 아니라 컨텍스트 효율을 위한 권장값입니다.

공식 사양과 실무 설계를 구분해야 한다

다음 항목은 Agent Skills의 공식 필수 Frontmatter가 아닙니다.

역할
목표
입력 조건
허용 범위
금지 범위
판단 기준
출력 형식
오류 처리
완료 기준
테스트 사례

그렇다고 불필요하다는 뜻은 아닙니다. 이것들은 보안 검토, 심사, 코드 리뷰처럼 결과의 일관성과 재현성이 중요한 업무에서 유용한 프롬프트 엔지니어링 및 에이전트 설계 패턴입니다.

구분	Agent Skills 공식 사양	실무 권장 설계
목적	호환 가능한 스킬 패키지 형식 정의	업무 결과의 일관성과 안전성 확보
필수 요소	SKILL.md, name, description	목적, 워크플로, 안전 경계, 출력 계약 등
본문 목차	강제하지 않음	업무 특성에 맞게 구조화
테스트	공식 필수 디렉터리 아님	트리거·정상·위험·경계 사례 권장
도구 권한	일부 메타데이터와 구현체 정책	읽기·쓰기·승인 범위를 명시적으로 설계

그림: 공식 사양과 실무 권장 설계의 경계 · Agent Skills Specification과 Best practices for skill creators을 바탕으로 재구성

보안·감사 스킬에 필요한 실무 구조

보안 업무용 스킬이라면 다음 구성을 권장할 수 있습니다.

구성 요소	중요도	설명
메타데이터	필수	이름, 트리거 설명, 버전, 호환 환경
목적	필수	만들어야 할 최종 결과
적용·비적용 조건	필수	호출해야 할 상황과 제외할 상황
입력 계약	권장	필수 입력, 선택 입력, 부족할 때의 행동
수행 절차	필수	작업 순서와 의사결정 흐름
판단 기준	중요	문제·위험도를 판정하는 근거
안전 경계	중요	금지 작업과 승인 필요 작업
도구 사용 정책	도구 사용 시 필수	읽기·쓰기·외부 전송 범위
출력 계약	필수	사람이 읽거나 시스템이 처리할 결과 구조
오류 처리	권장	실패, 불확실성, 정보 부족 처리
검증 기준	중요	완료 조건과 테스트 방법

목적은 완료 상태로 작성한다

나쁜 예:

IAM 정책을 분석한다.

좋은 예:

제공된 IAM 정책에서 과도한 권한, 권한 상승 경로,
신뢰 정책 오류와 조건문 누락을 식별하고,
각 발견의 근거와 최소 권한 수정안을 제공한다.

입력이 부족할 때도 행동을 정의한다

확인 가능한 위험은 먼저 분석한다.
확인할 수 없는 항목은 추정하지 않고 검토 제한 사항으로 표시한다.
SCP와 권한 경계가 없으면 전체 유효 권한을 확정하지 않는다.

안전 경계는 행동 권한으로 쓴다

읽기 작업                  자동 수행 가능
정책 수정안 생성            자동 수행 가능
실제 정책 변경              사용자 승인 필요
정책 삭제·권한 확대          기본 실행 금지
인증정보 원문 재출력          금지

“안전하게 행동한다”처럼 추상적으로 쓰기보다 어떤 동작을 자동 수행하고, 어떤 동작은 승인받고, 어떤 동작은 실행하지 않는지 구체화해야 합니다.

출력 계약과 오류 처리를 고정한다

사람이 읽는 보고서는 다음처럼 구성할 수 있습니다.

1. 검토 요약
2. 주요 발견 사항 표
3. 발견별 근거와 영향
4. 권한 상승 경로
5. 최소 권한 수정안
6. 검토 제한 사항
7. 추가로 필요한 정보

자동 후처리가 필요하다면 JSON Schema로 심각도, 확신도, 위치, 증거, 권고사항의 타입을 고정하는 편이 안정적입니다.

디렉터리는 역할별로 나누는 것이 좋다

긴 스킬 하나에 모든 정책과 예시를 몰아넣기보다 다음처럼 분리할 수 있습니다.

aws-iam-policy-review/
├── SKILL.md
├── references/
│   ├── severity-criteria.md
│   ├── privilege-escalation-patterns.md
│   ├── sensitive-actions.md
│   ├── condition-key-guidance.md
│   └── output-schema.json
├── scripts/
│   ├── validate_policy.py
│   └── normalize_statements.py
├── assets/
│   ├── report-template.md
│   └── sample-policy.json
└── tests/
    ├── trigger-evals.json
    ├── policy-cases/
    └── expected-results/

tests/는 공식 사양의 필수 디렉터리는 아니지만 운영 품질을 위해 추가할 수 있습니다. 핵심 워크플로는 SKILL.md, 긴 판정표는 references/, 결정적 검증은 scripts/, 출력 골격은 assets/, 회귀 검증은 tests/에 두면 관리하기 쉽습니다.

시스템 프롬프트, Agent Skills, MCP는 무엇이 다른가?

세 요소는 경쟁 관계가 아니라 서로 다른 층입니다.

구분	시스템 프롬프트	Agent Skills	MCP
질문	항상 어떻게 행동할 것인가?	특정 업무를 어떻게 수행할 것인가?	어떤 데이터·도구와 어떻게 연결할 것인가?
적용 범위	모든 요청	관련 작업에서만	연결된 서버의 리소스·도구
주요 내용	전체 원칙과 최상위 경계	도메인 절차·판단·예시	Resources·Prompts·Tools 통신
로딩	대화 시작부터	필요할 때	연결·호출 시
스크립트·자료	보통 포함하지 않음	함께 패키징 가능	외부 시스템이 기능 제공

AWS IAM 검토를 예로 들면 다음처럼 결합합니다.

시스템 프롬프트
└── 승인 없는 변경 금지, 비밀 보호

Agent Skill
└── 정책 수집 → 정규화 → 위험 판단 → 수정안 작성 절차

MCP Tools
├── IAM 정책 조회
├── Access Analyzer 결과 조회
├── 공식 문서 검색
└── 보고서 저장

스킬은 도구에 접속하는 프로토콜이 아니고, MCP는 보안 검토 절차 자체를 정의하지 않습니다.

skills.sh는 무엇인가?

skills.sh는 Agent Skills 사양 자체가 아닙니다. Vercel이 운영하는 공개 스킬 검색 디렉터리이며, vercel-labs/skills에서 공개하는 skills CLI와 연결됩니다.

 

한 문장으로 구분하면 다음과 같습니다.

Agent Skills
= 스킬을 어떤 파일 형식으로 작성할 것인가

skills.sh
= 작성된 스킬을 어디서 찾고 여러 에이전트에 어떻게 설치할 것인가

구분	Agent Skills	skills.sh·skills CLI
성격	작성 형식·공개 사양	검색 디렉터리·설치 도구
핵심	SKILL.md 구조	npx skills 명령
역할	스킬 정의·로딩	발견·설치·업데이트·순위
시작·운영	Anthropic에서 시작, 공개 개발	Vercel
저장 위치	각 Git 저장소와 로컬 디렉터리	원본 저장소를 찾아 에이전트 경로에 배치
국제표준기관	아님	아님
비유	패키지 명세	검색 디렉터리와 범용 설치 관리자

skills CLI는 어떻게 사용하는가?

공개 저장소의 스킬 목록만 확인:

npx skills add vercel-labs/agent-skills --list

특정 스킬을 프로젝트 범위에 설치:

npx skills add vercel-labs/agent-skills \
  --skill web-design-guidelines

Codex에만 설치:

npx skills add vercel-labs/agent-skills \
  --skill web-design-guidelines \
  --agent codex

설치하지 않고 임시로 사용:

npx skills use \
  vercel-labs/agent-skills@web-design-guidelines \
  --agent claude-code

관리 명령:

npx skills list
npx skills update
npx skills remove <skill-name>
npx skills init aws-iam-policy-review

CLI는 현재 Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI 등 70여 개 에이전트 설치 경로를 지원합니다. 기본 설치 범위는 현재 프로젝트이며 -g 또는 --global을 사용하면 사용자 전역에 설치합니다. 설치 방식은 공통 사본을 가리키는 심볼릭 링크와 개별 파일 복사 중 선택할 수 있습니다.

skills.sh 순위와 Official의 의미

skills.sh 문서에 따르면 순위는 CLI가 수집한 익명 설치 통계를 바탕으로 합니다. 따라서 순위는 인기도와 발견 가능성을 보여줄 뿐, 정확성·보안성·유지보수 품질 점수가 아닙니다.

 

텔레메트리를 사용하지 않으려면 CLI가 안내하는 환경변수를 사용할 수 있습니다.

DISABLE_TELEMETRY=1 npx skills add owner/repo

DO_NOT_TRACK도 대체 설정으로 안내됩니다.

 

Official 목록은 해당 제품이나 기술을 만든 조직이 제공하는 스킬을 모아 보는 기능입니다. 하지만 다음 세 문장은 서로 다릅니다.

공식 제작자가 배포했다                 가능
Vercel이 내용 전체를 보증한다           아님
보안상 무조건 안전하고 최신이다          보장되지 않음

공식 제작자 스킬을 우선하는 것은 좋은 출발점이지만, 설치 전에 현재 커밋과 스크립트, 권한 요구사항을 확인해야 합니다.

공개 스킬은 왜 공급망 위험이 되는가?

스킬은 단순한 설명문이 아닐 수 있습니다.

SKILL.md
├── 명령 실행 절차
├── 파일 변경 지침
├── 외부 도구 사용 규칙
└── 기존 지침과 충돌할 수 있는 문장

scripts/
├── Python·Bash·JavaScript 실행 코드
├── 의존성 설치
└── 외부 통신

스킬 자체가 새로운 운영체제 권한을 만드는 것은 아닙니다. 그러나 에이전트가 이미 가진 파일, 셸, 네트워크, 저장소, 클라우드 권한을 특정 방향으로 사용하도록 유도할 수 있습니다.

 

악성 또는 부주의한 스킬은 다음 동작을 유도할 수 있습니다.

• 민감한 파일과 환경변수 읽기
• 외부 서버로 데이터 전송
• 저장소 코드와 설정 변경
• 패키지 또는 실행 파일 설치
• 클라우드 정책 변경과 배포
• 보안 검사 또는 상위 지침 우회 시도

skills.sh 보안 감사 페이지는 Gen Agent Trust Hub, Socket, Snyk 등의 결과를 모아 보여줍니다. 그러나 도구마다 판정 기준이 다르고, skills.sh 문서 역시 모든 스킬의 품질과 보안을 보장할 수 없으므로 설치 전에 직접 검토하라고 명시합니다.

기업에서는 어떻게 도입해야 할까?

공개 스킬을 곧바로 전역 설치하기보다 승인된 공급망을 구성하는 편이 안전합니다.

그림: 공개 스킬의 기업 도입 검토와 배포 흐름 · skills.sh Documentation과 vercel-labs/skills README를 바탕으로 재구성

공개 skills.sh·Git 저장소
        ↓
출처·라이선스 확인
        ↓
SKILL.md와 scripts 전체 검토
        ↓
외부 URL·의존성·요구 권한 분석
        ↓
검토된 커밋 고정
        ↓
사내 승인 저장소
        ↓
프로젝트 범위 설치
        ↓
샌드박스·최소 권한·사람 승인
        ↓
업데이트 전 diff와 회귀 테스트

통제 항목	권장 방안
출처	공식 조직 또는 검증된 저장소 우선
버전	브랜치 최신본 대신 검토된 커밋 고정
설치 범위	전역보다 프로젝트 단위 우선
코드 검토	SKILL.md뿐 아니라 scripts/ 전체 확인
외부 통신	도메인과 전송 데이터, 의존성 설치 검토
실행 권한	셸·네트워크·클라우드 쓰기 권한 최소화
비밀정보	불필요한 자격증명은 에이전트 환경에서 제거
고위험 작업	정책 변경·배포·삭제에 사람 승인 적용
업데이트	자동 추종보다 diff 검토와 재검증
배포	사내 미러 또는 승인된 Git 저장소 운영

특히 다음 명령은 편리하지만 검토되지 않은 저장소에는 사용하지 않는 편이 좋습니다.

npx skills add unknown-owner/unknown-repo --all -g -y

이는 모든 스킬을 전역 범위에 확인 없이 설치하는 조합이기 때문입니다. 먼저 --list로 스킬을 확인하고, 원본 커밋의 SKILL.md, scripts/, 외부 URL과 라이선스를 검토한 뒤 필요한 스킬만 프로젝트 범위에 설치하는 순서가 안전합니다.

npm과 같은 것인가?

비슷한 면은 있지만 완전히 같지는 않습니다.

구분	npm	skills.sh
원본 배포	레지스트리에 패키지 게시	주로 Git 저장소의 스킬을 발견·연결
설치 대상	JavaScript 패키지와 의존성	지침·스크립트·참고자료·자산
설치 위치	node_modules	에이전트별 스킬 디렉터리
주요 관리	패키지 버전·의존성	에이전트별 배치·검색·설치 통계
실행 위험	설치·런타임 코드	에이전트가 따르는 지침과 실행 코드

따라서 skills.sh는 “Agent Skills용 npm”이라고 단정하기보다 검색 디렉터리와 여러 에이전트를 위한 범용 설치 관리자를 합친 서비스라고 설명하는 편이 정확합니다.

최종 정리

Agent Skills, skills.sh, 시스템 프롬프트, MCP의 역할을 한 번에 정리하면 다음과 같습니다.

Agent Skills
= 업무 절차를 패키징하는 공개 파일 형식

SKILL.md 실무 설계
= 그 형식 안에 목적·절차·판단·안전·출력 기준을 채우는 방법

skills.sh
= 공개 스킬을 검색하고 여러 에이전트에 설치하는 디렉터리·CLI

시스템 프롬프트
= 모든 요청에 적용되는 상위 행동 원칙

MCP
= 외부 데이터와 도구를 연결하는 통신 프로토콜

Agent Skills가 공식적으로 강제하는 최소 요소는 작습니다. 하지만 실제 운영 품질은 SKILL.md의 워크플로, 판단 기준, 안전 경계, 오류 처리와 테스트에서 결정됩니다.

 

skills.sh의 검색 순위나 Official 표시는 발견을 돕는 신호이지 보안 보증서가 아닙니다. 공개 스킬을 코드 공급망처럼 검토하고, 고정된 버전과 프로젝트 단위 설치, 최소 권한, 사람 승인을 결합해야 안전하게 활용할 수 있습니다.

Agent Skills는 기관이나 국제표준이 아니라 공개 스킬 패키지 형식이고, skills.sh는 그 형식을 사용하는 스킬을 찾고 설치하는 생태계다. 형식의 호환성과 운영의 안전성은 별개의 문제다.

참고 자료

• Agent Skills Overview
• Agent Skills Specification
• agentskills/agentskills 사양 저장소
• Anthropic skills 저장소
• OpenAI — Build skills
• Agent Skills — Optimizing skill descriptions
• Agent Skills — Best practices for skill creators
• skills.sh Documentation
• skills.sh Security Audits
• vercel-labs/skills
• Model Context Protocol — Introduction