Claude Code, Codex, MCP 생태계에서 빠르게 확산 중인 SKILL.md 기반 Agent Skills를 개발자·1인 스튜디오·B2B 자동화 관점으로 정리한 실행 보고서입니다.
Agent Skills는 AI 에이전트에게 반복 가능한 업무 절차, 도메인 지식, 스크립트, 템플릿을 SKILL.md 중심의 폴더로 전달하는 방식입니다. 한마디로 “매번 프롬프트를 다시 쓰지 않고, 에이전트가 필요할 때만 꺼내 쓰는 업무 매뉴얼 + 실행 도구 패키지”입니다.
Agent Skills는 AI 에이전트의 기능을 확장하는 가벼운 공개 포맷입니다. 기본 구조는 하나의 폴더와 SKILL.md 파일이며, 필요하면 scripts/, references/, assets/ 같은 보조 리소스를 함께 넣습니다.
my-skill/ ├── SKILL.md # 필수: metadata + instructions ├── scripts/ # 선택: 실행 가능한 코드 ├── references/ # 선택: 긴 문서, 정책, API 참고자료 ├── assets/ # 선택: 템플릿, 브랜드 리소스, 예시 파일 └── agents/ # 선택: 특정 에이전트 설정
| 단계 | 에이전트가 읽는 것 | 효과 |
|---|---|---|
| Discovery | 스킬 이름과 설명 | 어떤 상황에서 쓸지 후보 판단 |
| Activation | 선택된 SKILL.md 전체 | 정확한 절차·체크리스트·규칙 로드 |
| Execution | 필요한 스크립트·참고자료·템플릿 | 문서 생성, 코드 변경, 테스트, 배포 등 수행 |
이 방식은 “모든 지식을 항상 프롬프트에 넣는 방식”보다 효율적입니다. 에이전트는 평소에는 짧은 설명만 알고 있다가, 실제 업무에 필요할 때만 깊은 절차를 읽습니다.
| 이유 | 설명 | 실무 의미 |
|---|---|---|
| 에이전트 업무가 복잡해짐 | 단순 질의응답보다 파일 수정, 테스트, 브라우저 조작, 문서 생성 같은 장기 작업이 늘어났습니다. | 업무별 절차를 명시한 스킬이 결과 품질을 안정화합니다. |
| 프롬프트 재사용의 한계 | 매번 긴 프롬프트를 붙여 넣으면 누락, 변형, 비용 문제가 생깁니다. | 스킬은 버전 관리 가능한 업무 매뉴얼 역할을 합니다. |
| Claude Code·Codex 양쪽 지원 | Anthropic과 OpenAI 모두 Agent Skills 개념을 공식 문서화했습니다. | 특정 도구에만 종속되지 않는 표준화 흐름이 생겼습니다. |
| MCP와 결합 | MCP가 외부 도구 연결 계층이라면, 스킬은 “언제, 어떤 순서로, 어떤 기준으로 도구를 쓸지”를 정의합니다. | API 자동화·사내 시스템 연계·보안 통제에 적합합니다. |
| 마켓플레이스화 | 공식·커뮤니티 스킬 목록이 빠르게 늘고 있습니다. | 처음부터 직접 만들지 않고 검증된 패턴을 참고할 수 있습니다. |
| 구분 | 현재 포지션 | 특징 | 추천 활용 |
|---|---|---|---|
| Claude Code Skills | 가장 성숙한 구현 중 하나 | .claude/skills/*/SKILL.md, 자동/수동 호출, bundled skills, subagent, dynamic context 지원 | 개발 자동화, 코드 리뷰, 디버깅, 배포 절차화 |
| Claude API Agent Skills | 문서·PPT·Excel·PDF 등 사전 구축 스킬 제공 | API, claude.ai, AWS, Microsoft Foundry에서 사용 가능 | 문서 자동 생성/분석 제품화 |
| OpenAI Codex Skills | Codex CLI/IDE/앱에서 지원 | SKILL.md + scripts/references/assets, 명시/암시 호출, plugin 배포 개념 | Codex 기반 개발 워크플로우 표준화 |
| Agent Skills Open Standard | 벤더 중립 포맷 | 필수 필드 name, description, 폴더명과 name 일치 | Claude, Codex, Cursor류 도구 간 재사용 |
| Awesome Agent Skills | 공식·커뮤니티 스킬 큐레이션 | Anthropic, Google Labs, Vercel, Stripe, Cloudflare, Sentry, Figma 등 다양한 출처 포함 | 스킬 아이디어와 구조 참고 |
| 카테고리 | 무엇을 자동화하나 | 대표 스킬 아이디어 | 우선순위 |
|---|---|---|---|
| 코드 리뷰·디버깅 | diff 분석, 위험 변경 감지, 테스트 실패 원인 분석 | code-reviewdebugsummarize-changes | 매우 높음 |
| 브라우저 기반 검증 | 앱 실행 후 실제 UI를 열어 동작 확인 | run-appverify-uiplaywright-qa | 매우 높음 |
| 문서 생성·편집 | PPTX, DOCX, XLSX, PDF 생성/검토/변환 | pptx-reportproposal-writerinvoice-generator | 매우 높음 |
| 데이터 분석·시각화 | CSV/Excel 분석, 차트 생성, 보고서 자동화 | data-auditdashboard-makerfinancial-analysis | 높음 |
| MCP 서버 생성·연계 | 사내 API, Gmail, Calendar, DB, SaaS 도구 연결 | mcp-server-generatorapi-connector | 높음 |
| DevOps·배포 | 배포 전 체크, 마이그레이션, 롤백, 릴리즈 노트 | deploy-checklistrelease-manager | 높음 |
| 프론트엔드·디자인 시스템 | UI 컴포넌트, Figma/디자인 가이드 반영, 접근성 점검 | frontend-polishdesign-system | 높음 |
| 보안·감사 | 권한, secret, 위험한 스크립트, supply-chain 점검 | security-reviewskill-audit | 필수 |
| 업무 자동화 | 견적서, 제안서, 이메일, 회의록, 고객 응대 템플릿화 | b2b-proposalmeeting-summary | 높음 |
| Self-improving Skills | 실패 로그와 평가 결과를 바탕으로 스킬 자체를 개선 | skill-optimizereval-loop | 실험 단계 |
--- name: summarize-changes description: Summarize uncommitted git changes, identify risks, and suggest a commit message. Use when the user asks what changed or wants to prepare a commit. --- ## Goal Summarize the current git diff and identify implementation risks. ## Steps 1. Inspect the current git diff. 2. Summarize changes in 3 bullets or fewer. 3. Flag risks: missing tests, error handling, security issues, hardcoded values. 4. Suggest one conventional commit message. ## Output format - Summary - Risks - Suggested commit message
scripts/로 분리하는 것이 좋습니다.
| 업무 | 만들 스킬 | 효과 |
|---|---|---|
| Claude Code 개발 | project-onboarding, run-and-verify, code-review, release-check | 새 프로젝트를 빠르게 이해하고, 변경 후 실제 실행 검증까지 자동화 |
| 견적서·제안서 작성 | proposal-writer, estimate-builder, brand-tone | 회사 톤앤매너, 가격 정책, 산출물 포맷 일관화 |
| 제약·CTD 문서 검토 | ctd-review, quality-checklist, mfds-submission | 검토 항목 누락 방지, 반복 보고서 구조 표준화 |
| 앱스토어/ASO 운영 | appstore-release, aso-copywriter, screenshot-check | 릴리즈 노트, 키워드, 스크린샷 체크리스트 재사용 |
| 티셔츠 목업 웹앱 개발 | mockup-engine, image-pipeline, frontend-polish | 이미지 합성 품질 기준, 테스트 절차, UI 요구사항 재사용 |
| B2B 자동화 컨설팅 | client-discovery, workflow-mapping, automation-prd | 고객 인터뷰 → 자동화 설계 → 개발 지시서까지 표준 프로세스화 |
스킬은 단순 문서가 아니라 에이전트의 행동을 바꾸는 실행 지침입니다. 특히 외부에서 받은 스킬이나 marketplace 스킬은 supply-chain 관점으로 검토해야 합니다.
scripts/ 내부 명령어 검토| 단계 | 기간 | 할 일 | 산출물 |
|---|---|---|---|
| 1단계 | 1일 | 반복 프롬프트 5개를 모아 스킬 후보 선정 | 스킬 백로그 |
| 2단계 | 2~3일 | instruction-only 스킬 3개 작성: 코드리뷰, 실행검증, 제안서 | .claude/skills/ 초기 세트 |
| 3단계 | 1주 | 실제 프로젝트에 적용하고 실패 케이스 기록 | 개선된 description, 체크리스트 |
| 4단계 | 2주 | 반복 명령을 scripts로 분리하고 테스트 추가 | 실행형 스킬 |
| 5단계 | 상시 | 보안 감사, 버전 관리, 조직 템플릿화 | 개인/프로젝트/고객별 스킬 라이브러리 |
code-review — diff 기반 위험 분석run-and-verify — 앱 실행 후 실제 동작 확인claude-code-handoff — Claude Code 전달용 개발 지시서 생성proposal-writer — B2B 제안서/견적서 작성html-report — 최신 자료 조사 후 HTML 보고서 생성prd-writer — 서비스 기획서/PRD 작성appstore-aso — 앱스토어 문구·키워드·스크린샷 검토mcp-server-generator — API 문서 기반 MCP 서버 설계security-audit — secret, 권한, 위험 명령 검사document-review — PDF/DOCX/PPTX 구조화 검토| 자료 | 핵심 내용 | 링크 |
|---|---|---|
| Claude Code Skills Docs | Claude Code에서 SKILL.md 작성, 자동/수동 호출, bundled skills, 위치 규칙 설명 | code.claude.com/docs/en/skills |
| Claude API Agent Skills Docs | Agent Skills 개념, 사전 구축 문서 스킬, API·claude.ai·AWS·Microsoft Foundry 지원 설명 | platform.claude.com/docs/.../agent-skills |
| OpenAI Codex Skills Docs | Codex Skills 구조, progressive disclosure, 명시/암시 호출, plugin 배포 개념 | developers.openai.com/codex/skills |
| Agent Skills Open Standard | 공개 표준, 폴더 구조, name/description 규격 | agentskills.io/home, specification |
| Anthropic Skills GitHub | 공식 샘플 스킬 저장소. 문서/PPT/PDF/Excel 스킬 구조 참고 가능 | github.com/anthropics/skills |
| Awesome Agent Skills | 공식·커뮤니티 스킬 큐레이션. 다양한 회사와 도구의 스킬 목록 | github.com/VoltAgent/awesome-agent-skills |
| Agent Skills Data Analysis | 공개 스킬 40,285개 분석. 소프트웨어 엔지니어링 중심, 안전 리스크 지적 | arxiv.org/abs/2602.08004 |
| SkillOpt | 평가 결과를 바탕으로 스킬 문서를 점진적으로 최적화하는 연구 | arxiv.org/abs/2605.23904 |
| MCP Tools Evidence | 177,000개 MCP 도구 분석. action tool 비중 증가와 감독 필요성 제시 | arxiv.org/abs/2603.23802 |
| Semantic Supply-chain Attacks | SKILL.md 설명·지침이 검색/선택/거버넌스를 조작할 수 있음을 분석 | arxiv.org/abs/2605.11418 |
이 문서는 2026-06-16 기준 공개 문서와 최신 검색 결과를 바탕으로 작성되었습니다. 제품 기능은 빠르게 바뀔 수 있으므로 실제 도입 전 공식 문서를 재확인하세요.