Agent Skills 사양에 맞춰 SKILL.md의 YAML 프론트매터와 본문을 분석합니다. 오류 및 경고 사항 확인, 토큰 수 추정, CSV 내보내기 기능을 제공합니다.
AI 에이전트가 특정 작업을 수행하도록 지시하는 Agent Skills 형식은 개발자에게 매우 유용한 표준입니다. 이 형식의 핵심은 바로 SKILL.md 파일입니다. 기본적으로 이 파일은 YAML 프론트매터와 Markdown 본문으로 구성됩니다. 에이전트는 먼저 프론트매터에 있는 이름과 설명을 읽고, 해당 스킬을 활성화할지 결정한 후 본문을 로드합니다. 따라서 파일 구조를 정확하게 작성하는 것이 중요합니다. SKILL.md 검증기를 사용하면 브라우저에서 즉시 이 파일의 구조가 표준 규격에 맞는지 확인할 수 있습니다. 에이전트가 스킬을 올바르게 인식하려면 폴더 안에 SKILL.md 파일이 위치해야 하며, 프론트매터가 올바르게 닫혀 있어야 합니다. 본문의 지시사항이 아무리 훌륭해도 형식이 잘못되면 에이전트가 이를 무시하거나 오류를 발생시킬 수 있습니다.
SKILL.md 파일의 상단에 위치하는 YAML 프론트매터는 에이전트가 스킬의 메타데이터를 이해하는 데 사용됩니다. 여기에는 반드시 포함해야 하는 필수 필드와 상황에 따라 추가하는 선택 필드가 있습니다. name과 description은 필수이며, 나머지 필드는 선택 사항입니다. 각 필드에는 엄격한 글자 수 제한이 적용됩니다. SKILL.md 검증기는 이러한 제한을 자동으로 검사하여 규격 위반을 찾아냅니다.
| 필드 | 필수 여부 | 최대 길이 제한 |
|---|---|---|
name |
필수 | 64자 |
description |
필수 | 1,024자 |
compatibility |
선택 | 500자 |
name 필드는 소문자, 숫자, 단일 하이픈만 사용할 수 있으며 최대 64자를 넘을 수 없습니다. 또한 선택적으로 입력한 폴더 이름과 일치해야 합니다. description은 최대 1,024자까지 작성할 수 있습니다. YAML 문법 오류를 방지하기 위해 콜론이나 특수문자가 포함된 값은 따옴표로 감싸는 것이 좋으며, 복잡한 구조를 디버깅할 때는 YAML을 JSON으로 변환하여 구조를 확인하는 것도 도움이 됩니다.
description 필드는 단순한 소개글이 아니라 에이전트가 해당 스킬을 사용할지 결정하는 트리거 역할을 합니다. 에이전트는 사용자의 요청을 분석한 후, 가장 적합한 스킬을 선택하기 위해 이 설명 한 줄에 의존합니다. SKILL.md 검증기는 설명이 60자 미만일 경우 경고를 표시합니다. 너무 짧은 설명은 에이전트가 스킬의 정확한 용도를 파악하지 못하게 만드는 가장 흔한 원인입니다. 효과적인 설명은 무엇을 하는지와 언제 사용하는지를 명확히 포함해야 합니다. 예를 들어, 데이터를 분석합니다라는 모호한 설명 대신 사용자가 CSV 파일의 매출 데이터를 제공했을 때 월별 추이를 분석하고 보고서를 생성할 때 사용과 같이 구체적인 조건을 명시하는 것이 좋습니다. 언제 사용하는지에 대한 문구가 부족하면 검증기에서 참고 사항으로 지적합니다. 명확한 트리거 조건을 작성하면 에이전트가 스킬을 훨씬 더 정확하게 호출할 수 있습니다.
프론트매터 아래의 Markdown 본문은 에이전트가 실제로 수행할 작업의 세부 지시사항을 담고 있습니다. 하지만 본문이 무조건 길다고 좋은 것은 아닙니다. Agent Skills 규격은 본문을 500줄 이하로 유지하고, 대략 5,000개의 토큰 예산 내에서 작성할 것을 권장합니다. 검증기는 문자 4개당 1개의 토큰으로 추정하여 이 한도를 검사합니다. 본문의 길이가 너무 길어지면 JSON을 YAML로 변환하는 과정에서 불필요한 중첩을 줄이는 등 구조를 단순화하는 노력이 필요합니다. 또한 파일 참조는 상대 경로를 사용해야 하며, 깊이가 1단계를 넘지 않는 것이 좋습니다. 절대 경로나 지나치게 중첩된 파일 링크는 경고의 대상이 됩니다. 마지막으로, 본문에 TODO나 lorem ipsum 같은 임시 텍스트가 남아있는지 확인해야 합니다. 이러한 임시 텍스트가 남아있으면 검증기가 경고를 발생시키며, 실제 프로덕션 환경에서 에이전트가 잘못된 지시를 따를 수 있습니다.
SKILL.md 파일을 작성할 때 주의해야 할 점 중 하나는 표준 규격 필드와 특정 환경 전용 확장 필드의 차이입니다. model이나 hooks 같은 필드는 Claude Code 환경에서는 유용하게 사용되지만, 다른 에이전트에서는 무시됩니다. SKILL.md 검증기는 이러한 필드가 포함되어 있을 때 오류가 아닌 참고 사항으로 표시하여 호환성을 안내합니다. 표준 규격에 정의되지 않은 사용자 정의 키를 추가하고 싶다면 metadata 필드 아래에 중첩하여 작성하는 것이 올바른 방법입니다. 또한 allowed-tools 필드는 현재 실험적 기능이며, YAML 리스트 형식이 아닌 공백으로 구분된 문자열로 작성해야 합니다. 리스트 형식으로 작성하면 검증기에서 경고가 발생합니다. 스킬을 다양한 에이전트 환경에서 이식성 높게 사용하려면 표준 필드 위주로 구성하고, 환경 종속적인 설정은 최소화하는 것이 좋습니다.
SKILL.md 검증기를 실행하면 오류, 경고, 참고 사항으로 구분된 상세 보고서를 받을 수 있습니다. 오류는 규격을 위반하여 에이전트가 스킬을 로드하지 못하게 만드는 치명적인 문제입니다. 경고는 규격의 권장 사항을 따르지 않았거나 잠재적인 문제를 일으킬 수 있는 부분이며, 참고 사항은 환경 종속 필드나 실험적 기능에 대한 안내입니다. 파일이 유효하다는 것은 오류가 0개라는 것을 의미합니다. 경고가 있더라도 파일 자체는 유효한 것으로 간주됩니다. 보고서는 파일 통계와 발견된 문제 목록을 표로 제공하며, 이를 CSV 형식으로 내보볼 수 있습니다. 이 도구는 연결된 파일의 실제 존재 여부나 지시사항의 논리적 품질을 평가하지는 않습니다. 무엇보다 중요한 점은 모든 검증 과정이 브라우저 로컬에서 실행된다는 것입니다. 파일이 외부 서버로 업로드되지 않으므로, 사내 보안이 중요한 워크플로우나 민감한 정보가 포함된 스킬도 안심하고 검사할 수 있습니다.
SKILL.md 파일의 전체 내용을 복사하여 입력창에 붙여넣고 실행 버튼만 누르면 됩니다. 폴더 이름이 있다면 선택 사항으로 함께 입력할 수 있으며, 결과는 오류, 경고, 참고 사항으로 나누어 표로 제공됩니다.
아닙니다. SKILL.md 검증기는 모든 파싱과 검사를 브라우저 로컬 환경에서 처리하므로 파일 내용이 외부로 전송되지 않습니다. 내부 워크플로우가 포함된 스킬도 안심하고 검사할 수 있으며, 무료이고 회원가입도 필요하지 않습니다.
name과 description 두 가지가 필수입니다. name은 소문자, 숫자, 단일 하이픈만 사용할 수 있고 최대 64자까지 허용되며, description은 최대 1,024자까지 작성할 수 있습니다.
가장 흔한 원인은 description이 너무 모호하거나 짧아서 에이전트가 해당 스킬을 언제 사용해야 할지 판단하지 못하는 경우입니다. SKILL.md 검증기는 description이 60자 미만일 때 경고를 표시하며, 언제 사용할지에 대한 명확한 문구가 포함되어 있는지 확인하는 것이 좋습니다.
오류가 아니라 참고 사항으로 분류됩니다. 이러한 필드는 Claude Code에서만 인식하는 확장 기능이며, 다른 에이전트에서는 무시됩니다. 표준 Agent Skills 규격과의 호환성을 확인하려면 metadata 필드 안에 넣거나 참고 사항 메시지를 확인하세요.
주로 콜론 뒤에 공백이 없거나, 탭 문자를 사용했거나, 들여쓰기가 잘못된 경우 발생합니다. JSON을 YAML로 변환하는 도구를 활용해 보거나, YAML을 JSON으로 변환하여 구조를 확인해 볼 수도 있습니다.
문자 4개당 토큰 하나로 계산하는 대략적인 추정치입니다. 실제 토크나이저는 모델마다 다르며, 특히 한국어와 같은 비라틴 문자의 경우 실제 토큰 수와 차이가 있을 수 있으므로 참고용으로만 활용하시기 바랍니다.
두 도구 모두 동일한 Agent Skills 규격 규칙을 적용하지만, SKILL.md 검증기는 설치 없이 브라우저에서 바로 사용할 수 있고 길이 가이드라인과 Claude Code 관련 참고 사항을 추가로 제공합니다. 다만 폴더 전체가 아닌 단일 파일 내용만 검사할 수 있습니다.
