Agent Skills: AI를 위한 업무 매뉴얼

AI 코딩 에이전트를 사용하다 보면 같은 종류의 작업을 반복적으로 요청하게 될 때가 있습니다. 예를 들어, “이 프로젝트에서는 Jest 대신 Vitest를 사용해”, “API 테스트를 작성할 때는 이런 패턴을 따라줘”, “마이그레이션 스크립트를 작성할 때는 항상 롤백 코드도 함께 작성해” 같은 지시를 매번 반복하게 되죠. 🤔

AGENTS.md나 CLAUDE.md 같은 컨텍스트 파일로 프로젝트 전반에 대한 정보를 제공할 수 있지만, 특정 작업에 대한 세부 지침까지 모두 담기에는 한계가 있습니다. 컨텍스트 파일이 너무 길어지면 AI가 읽는 데 시간이 걸리고, 정작 중요한 정보가 묻혀버릴 수 있거든요.

이런 문제를 해결하기 위해 등장한 것이 바로 Skills입니다. 이 글에서는 Skills가 무엇인지, 어떻게 활용할 수 있는지 알아보겠습니다.

Skills란 무엇인가요?

Skills는 AI 코딩 에이전트가 특정 작업을 수행할 때 참조하는 지침, 스크립트, 리소스의 집합입니다. skills.sh에서는 이를 “procedural knowledge(절차적 지식)“라고 표현하는데요, AI 에이전트가 특정 작업을 더 효과적으로 수행할 수 있도록 도와주는 플러그인이나 확장 기능이라고 생각하면 됩니다.

AGENTS.md나 CLAUDE.md 같은 컨텍스트 파일은 프로젝트 전반에 대한 정보를 담습니다. 빌드 명령어, 코드 스타일 가이드, 테스트 실행 방법 같은 것들이죠. 반면 Skills는 특정 도메인이나 작업에 특화된 지침입니다. 예를 들어 “데이터베이스 마이그레이션 작성하기”, “API 엔드포인트 추가하기”, “성능 최적화 분석하기” 같은 구체적인 작업에 대한 노하우를 담을 수 있습니다.

컨텍스트 파일이 “우리 회사의 개발 문화”라면, Skills는 “특정 업무의 작업 매뉴얼”이라고 생각하면 됩니다. Skills는 자체 문서화(Self-documenting)되어 있어서 사람이 읽고 이해하기 쉽고, 확장 가능(Extensible)해서 단순한 텍스트부터 실행 코드까지 다양한 복잡도를 지원하며, 이식 가능(Portable)해서 버전 관리나 공유가 쉽습니다.

Skills의 구조

Skills는 일반적으로 다음과 같은 구조를 가집니다:

.agent/skills/
├── database-migration/
│   ├── SKILL.md              # 핵심 지침 파일
│   ├── scripts/
│   │   └── validate-migration.sh
│   └── examples/
│       ├── add-column.md
│       └── create-table.md
└── api-endpoint/
    ├── SKILL.md
    └── examples/
        └── rest-crud.md

SKILL.md가 핵심 파일입니다. YAML frontmatter에 설명을 담고, 마크다운으로 상세 지침을 작성합니다:

---
description: 데이터베이스 마이그레이션 스크립트 작성 가이드
---

# 데이터베이스 마이그레이션

마이그레이션 스크립트를 작성할 때는 다음 규칙을 따릅니다.

## 파일 명명 규칙

마이그레이션 파일은 `YYYYMMDD_HHMMSS_description.sql` 형식으로 작성합니다.

## 필수 사항

1. 모든 마이그레이션은 롤백(down) 스크립트를 함께 작성합니다
2. 대량 데이터 변경 시 배치 처리를 고려합니다
3. 인덱스 추가는 CONCURRENTLY 옵션을 사용합니다

## 예제

examples/ 디렉토리의 예제를 참고하세요.

scripts/ 디렉토리에는 Skill과 관련된 헬퍼 스크립트를 저장합니다. 마이그레이션 유효성 검사, 자동 생성 스크립트 등을 넣을 수 있죠.

examples/ 디렉토리에는 참고할 수 있는 예제들을 저장합니다. AI가 작업할 때 이 예제들을 참고해서 일관된 코드를 생성할 수 있습니다.

한 가지 팁을 드리자면, SKILL.md 파일은 5,000토큰 이하로 유지하는 것이 권장됩니다. agentskills.io 공식 스펙에 따르면, Skills는 Progressive Disclosure(점진적 공개) 방식으로 작동하는데요, 세 단계로 나누어 볼 수 있습니다.

첫 번째 Discovery 단계에서는 시작 시 각 Skill의 이름과 설명만 로드합니다. 약 100토큰 정도로, 어떤 Skill이 언제 관련될지 파악하는 데 충분한 정보만 가져옵니다. 두 번째 Activation 단계에서는 작업이 Skill의 설명과 매칭되면 전체 SKILL.md 내용을 컨텍스트에 로드합니다. 세 번째 Execution 단계에서는 AI가 지침을 따라 실행하며, 필요시 scripts/나 references/ 디렉토리의 파일을 추가로 로드합니다.

이렇게 단계별로 필요한 정보만 로드하기 때문에 컨텍스트 윈도우를 효율적으로 사용할 수 있습니다.

왜 Skills가 필요한가요?

Skills의 가장 큰 장점은 반복 작업의 표준화입니다. 한 번 잘 정리해두면 같은 유형의 작업을 할 때마다 일일이 설명할 필요가 없습니다. “데이터베이스 마이그레이션 Skill을 참고해서 users 테이블에 email_verified 컬럼을 추가해줘”라고만 하면 됩니다.

또한 팀 간 지식 공유에도 효과적입니다. 경험 많은 개발자가 작성한 Skills를 팀 전체가 활용할 수 있으니까요. 팀의 코딩 컨벤션, 코드 리뷰 체크리스트, 보안 가이드 같은 것들을 전부 Skills로 만들어두면, 새로 합류한 팀원에게 “이 프로젝트에서는 이렇게 해”라고 설명하는 대신 “이 스킬부터 설치하고 시작하세요”라고 말할 수 있습니다. 신입 개발자 온보딩 문서를 사람 대신 AI에게 먼저 읽히는 시대가 온 것이죠.

복잡한 작업의 캡슐화도 가능합니다. 여러 단계로 이루어진 복잡한 작업도 하나의 Skill로 정리해두면 AI가 단계별로 올바르게 수행할 수 있습니다. 예를 들어 “새 마이크로서비스 생성하기” Skill에는 프로젝트 구조 생성, 기본 설정 파일 작성, CI/CD 파이프라인 설정, 문서 템플릿 생성 등의 단계가 모두 포함될 수 있습니다.

Skills 활용 예시

실제로 Skills를 어떻게 활용할 수 있는지 몇 가지 예시를 살펴보겠습니다.

코드 리뷰 체크리스트 Skill을 만들어두면 AI에게 코드 리뷰를 요청할 때 팀의 리뷰 기준에 맞춰 분석하도록 할 수 있습니다. 보안 취약점 점검, 성능 이슈 확인, 코딩 컨벤션 준수 여부 등을 일관되게 검토할 수 있죠.

---
description: 우리 팀의 코드 리뷰 체크리스트
---

# 코드 리뷰 가이드

코드 리뷰를 요청받으면 다음 항목을 순서대로 검토합니다.

## 보안
- SQL 인젝션, XSS 취약점이 없는지 확인
- 민감한 정보(API 키, 비밀번호)가 하드코딩되어 있지 않은지 확인
- 사용자 입력 데이터가 적절히 검증되는지 확인

## 성능
- N+1 쿼리 문제가 없는지 확인
- 불필요한 리렌더링이 발생하지 않는지 확인
- 큰 데이터 처리 시 페이지네이션이 적용되어 있는지 확인

## 코드 품질
- 함수가 한 가지 일만 하는지 확인
- 매직 넘버 대신 상수를 사용하는지 확인
- 에러 처리가 적절히 되어 있는지 확인

API 문서 작성 Skill을 정의해두면 새 엔드포인트를 추가할 때마다 동일한 형식의 문서가 자동으로 생성됩니다. 요청/응답 예시, 에러 코드 설명, 인증 요구사항 등을 빠뜨리지 않고 작성할 수 있습니다.

테스트 코드 작성 Skill에는 팀에서 선호하는 테스트 패턴, 모킹 방법, 픽스처 작성 규칙 등을 담을 수 있습니다. AI가 테스트 코드를 작성할 때 이 Skill을 참고하면 팀의 컨벤션에 맞는 테스트가 생성됩니다.

Skills을 지원하는 도구들

Skills는 Claude Code, Cursor, Windsurf 등 주요 AI 코딩 에이전트에서 사용할 수 있습니다. 각 도구마다 구현 방식이 조금씩 다르지만 핵심 개념은 동일합니다.

Claude Code에서는 .agent/skills/ 디렉토리에 Skills를 저장하고, AI가 관련 작업을 수행할 때 자동으로 참조합니다. Cursor는 .cursor/rules/ 디렉토리에 .mdc 형식의 규칙 파일을 저장하고, glob 패턴으로 특정 파일에만 규칙을 적용할 수 있어서 Skills와 비슷한 역할을 합니다. GitHub Copilot은 .github/instructions/ 디렉토리에 컨텍스트별 지침 파일을 저장할 수 있습니다.

아직 도구마다 구현 방식이 달라서 호환성 문제가 있지만, agentskills.io에서 Anthropic이 Agent Skills 공식 스펙을 호스팅하고 있어서 AGENTS.md처럼 점차 표준화될 가능성이 높습니다.

Skills를 찾을 수 있는 곳

Skills를 직접 만들지 않아도 다른 개발자들이 공유한 Skills를 활용할 수 있습니다. 이미 커뮤니티에서 다양한 Skills 디렉토리 사이트가 등장했습니다.

skills.sh는 2026년 1월 Vercel에서 출시한 Skills 디렉토리로, “AI 에이전트를 위한 npm”이라고 불립니다. 200개 이상의 스킬이 등록되어 있고, vercel-react-best-practices, test-driven-development, shadcn-ui 같은 인기 Skills를 리더보드에서 확인할 수 있습니다. 출시 직후 Stripe, Anthropic, Expo, Remotion 같은 기업들이 공식 Skills를 배포했을 정도로 빠르게 성장하고 있습니다.

cursor.directory는 Cursor 사용자들을 위한 규칙 디렉토리입니다. 7만 명 이상의 커뮤니티 멤버가 있으며, Next.js, React, Python, Vue.js 등 다양한 프레임워크별 Cursor Rules를 찾을 수 있습니다. MCP 서버 설정도 함께 제공해서 Cursor 환경을 빠르게 구성하는 데 도움이 됩니다.

이 외에도 skillsmp.com, PRPM, OpenSkills 같은 대안들이 있어서 Skills 생태계가 빠르게 확장되고 있습니다. 직접 Skills를 만들기 전에 이런 사이트들을 먼저 둘러보면 시간을 절약할 수 있습니다.

마치며

Skills는 AI 코딩 에이전트를 더 효과적으로 활용하기 위한 새로운 방법입니다. 컨텍스트 파일이 “AI에게 프로젝트를 소개하는 문서”라면, Skills는 “AI를 조직의 지식을 장착한 동료 개발자”로 만들어주는 도구라고 할 수 있죠.

이제 AI 활용의 경쟁력이 모델 성능에서 “어떤 Skills를 가지고 있느냐”로 점점 이동하고 있습니다. 같은 코딩 에이전트를 써도 누군가는 그냥 모델을 그대로 쓰고, 누군가는 프론트엔드, 백엔드, 보안, 사내 컨벤션 Skills를 잔뜩 깔아놓고 쓰는 것이죠. 그러면 사실상 완전히 다른 AI를 쓰는 것과 비슷한 효과가 날 겁니다.

우리가 흔히 말하는 “AI 잘 쓰는 사람”이라는 것도, 앞으로는 프롬프트 잘 치는 사람이 아니라 어떤 Skills를 설계하고 어떤 Skills를 조합하느냐를 잘하는 사람이 될 것 같습니다. 그런 의미에서 skills.sh 같은 디렉토리는 단순한 도구라기보다는 AI 개발 문화가 어디로 가고 있는지를 보여주는 신호 같은 느낌입니다.

AI 에이전트를 위한 컨텍스트 파일에 대해 더 알고 싶다면 AGENTS.md와 CLAUDE.md에 대한 포스팅을 참고해 주세요. Skills 시스템이 실제로 어떻게 활용되는지 궁금하다면 Moltbook: AI 에이전트들의 소셜 네트워크에서 마크다운 기반 스킬로 에이전트를 확장하는 사례를 확인해 보세요. 직접 Skill을 설계하고 SKILL.md를 작성하는 방법은 Agent Skill 만들기: SKILL.md 작성 가이드에서 다루고 있습니다. Skills를 서브 에이전트에 주입해서 전문화된 AI 어시스턴트를 만드는 방법은 클로드 코드 서브 에이전트에서 다루고 있습니다.