<img src="https://ai.23yellow.com/data/editor/2608/3232235521_AOqYD4RG_1788011736.png" alt="image" width="512" /> # <span>《All You Need to Know About SKILL.md》 요약</span> ## <span>원문 정보</span> * **<span>제목:</span>**<span> All You Need to Know About SKILL.md</span> * **<span>부제:</span>**<span> What Agent Skills Are, How to Build One, Where to Find the Ones Others Have Built, and How to Share Your Own</span> * **<span>저자:</span>**<span> Aishwarya Srinivasan</span> * **<span>게시일:</span>**<span> 2026년 7월 12일</span> * **<span>원문:</span>**<span> </span>[<span>AI with Aish — All You Need to Know About SKILL.md</span>](https://aishwaryasrinivasan.substack.com/p/all-you-need-to-know-about-skillmd) * **<span>열람 범위:</span>**<span> 공개 본문 1\~4절 기준. 5\~9절은 ‘계속 읽기/유료’ 구간이어서 목차만 확인됨.</span> ## <span>한 문장 핵심</span> `<span>SKILL.md</span>`<span>는 더 긴 프롬프트가 아니라, 반복 업무의 절차·판단 기준·예외·검증법을 재사용 가능한 폴더로 패키징하는 </span>**<span>AI용 업무 매뉴얼</span>**<span>이다.</span> ## <span>핵심 내용</span> ### <span>1\. Skill은 파일이 아니라 폴더다</span> <span>필수 진입점은 </span>`<span>SKILL.md</span>`<span>이며, 필요에 따라 실행 스크립트, 참고 문서, 템플릿·이미지 같은 자산을 함께 둔다. 새 직원을 위한 온보딩 문서처럼 “무엇을, 어떤 순서와 기준으로, 어떤 실수를 피하며 수행하는가”를 담는다.</span> ### <span>2\. MCP와의 차이</span> | <span>구분</span> | <span>역할</span> | | --- | --- | | <span>MCP</span> | <span>도구·API·데이터 접근을 제공한다. 즉, </span>**<span>무엇을 할 수 있는가</span>**<span>를 확장한다.</span> | | <span>Skill</span> | <span>도구를 활용하는 절차와 품질 기준을 제공한다. 즉, </span>**<span>어떻게 잘할 것인가</span>**<span>를 규정한다.</span> | <span>둘은 경쟁 관계가 아니라 상호 보완 관계다.</span> ### <span>3\. 점진적 공개\(Progressive Disclosure\)</span> <span>에이전트는 처음부터 모든 지침을 읽지 않는다. 먼저 각 Skill의 </span>`<span>name</span>`<span>과 </span>`<span>description</span>`<span>만 보고 관련성을 판단한 뒤, 필요한 경우에만 </span>`<span>SKILL.md</span>`<span>와 참조 파일을 차례로 불러온다. 따라서 </span>`<span>description</span>`<span>은 단순 소개가 아니라 </span>**<span>호출 조건</span>**<span>이다. 실제 사용자가 쓸 표현, 적용 범위, 제외 조건을 구체적으로 써야 한다. 긴 내용과 드물게 쓰는 정보는 별도 참조 파일로 분리한다.</span> ### <span>4\. 기본 구조</span> ``` my-skill/ ├── SKILL.md ├── scripts/ # 반복 실행·검증 자동화 ├── references/ # 스타일 가이드, 규칙, 지식 └── assets/ # 템플릿, 이미지, 결과물 재료 ``` `<span>SKILL.md</span>`<span>는 YAML frontmatter의 </span>`<span>name</span>`<span>, </span>`<span>description</span>`<span>과 Markdown 지침으로 구성한다. 본문에는 목적, 사용/비사용 조건, 필요한 입력, 단계별 작업 흐름, 출력 형식, 금지사항, 최종 품질 검사를 적는다.</span> ### <span>5\. 만드는 방법</span> <span>파일 구조부터 설계하지 말고, 먼저 반복되는 2\~3개 실제 업무를 고른다. 업무를 한 번 수행하면서 필요한 입력, 성공한 단계, 사용자의 수정 요구, 좋은 입출력 예시, 흔한 오류와 예외를 기록한 뒤 Skill로 전환한다. 첫 버전은 좁게 만들고 실제 사용 결과에 따라 스크립트·참조·템플릿을 추가한다.</span> ### <span>6\. 테스트 기준</span> * <span>관련 요청에서 정확히 호출되는가?</span> * <span>무관한 요청에서는 호출되지 않는가?</span> * <span>정해진 절차와 출력 형식을 따르는가?</span> * <span>표현이 다른 유사 요청에서도 결과가 일관적인가?</span> * <span>필수 항목, 테스트, 계산, 인용, 템플릿 일치 여부를 마지막에 검증하는가?</span> <span>긍정 트리거, 부정 트리거, 경계 사례를 여러 번 시험해야 한다. 터미널·로컬 파일·연결 앱에 의존하는 Skill은 실행 환경에 따라 동작 범위가 달라질 수 있다.</span> ## <span>예시에서 얻을 수 있는 설계 원칙</span> <span>글의 PR 정리 Skill은 Git 사용법 자체를 길게 설명하지 않는다. 대신 충돌 해결, 리뷰 반영, 테스트 실행, 실패 원인 분류, 재검증, 변경 요약이라는 </span>**<span>조직 고유의 절차</span>**<span>와 “테스트를 지워 통과시키지 않는다” 같은 </span>**<span>사고 방지 규칙</span>**<span>에 집중한다. 좋은 Skill의 가치는 일반 지식보다 반복 업무의 순서·판단·금지사항을 명시하는 데 있다.</span> ## <span>실무 체크리스트</span> * <span>반복해서 재설명하는 업무인가?</span> * `<span>description</span>`<span>에 실제 요청 문구와 제외 조건이 있는가?</span> * <span>필요한 입력과 누락 시 대응이 명확한가?</span> * <span>작업 순서, 예외, 중단 조건이 구체적인가?</span> * <span>결과 형식과 품질 기준을 검증할 수 있는가?</span> * <span>긴 참고자료는 </span>`<span>references/</span>`<span>로 분리했는가?</span> * <span>관련·무관·경계 요청을 모두 테스트했는가?</span> * <span>외부에서 받은 Skill의 스크립트와 권한을 검토했는가?</span> ## <span>확인하지 못한 원문 구간</span> <span>목차상 후반부는 다음 주제를 다룬다: Skill을 망가뜨리는 규칙, 공개 Skill 탐색, GitHub 배포, 신뢰할 수 없는 Skill의 보안 감사, 참고 링크 모음. 현재 공개 열람 범위에서는 해당 본문을 확인할 수 없어 세부 내용을 추정하지 않았다.</span> ## <span>결론</span> <span>좋은 Skill은 “AI에게 모든 것을 가르치는 문서”가 아니다. 반복 업무에 필요한 최소한의 절차와 조직 지식을 정확한 트리거, 명확한 출력 계약, 검증 가능한 품질 기준으로 묶은 실행 가능한 업무 표준이다. 먼저 실제 작업을 성공시키고, 그 과정을 작게 문서화한 뒤, 사용하면서 지속적으로 개선하는 방식이 가장 실용적이다.</span> ## <span>참고 및 교차 검증</span> * [<span>요약 대상 원문 — AI with Aish</span>](https://aishwaryasrinivasan.substack.com/p/all-you-need-to-know-about-skillmd) * [<span>Agent Skills 개요</span>](https://agentskills.io/home) * [<span>Agent Skills 명세</span>](https://agentskills.io/specification) * [<span>Skill 작성 모범 사례</span>](https://agentskills.io/skill-creation/best-practices) * [<span>Anthropic — Agent Skills 설계 원칙</span>](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)