SKILL.md Standard Template
새 스킬 작성 시 아래 구조를 출발점으로 사용합니다. 실제 작업에 필요 없는 섹션은 넣지 않습니다.
Frontmatter Schema
---
name: <skill-name> # 필수. 소문자 하이픈 (예: doc-docx)
description: | # 필수. 목적 + 트리거 키워드
<스킬 목적을 서술형으로 작성>
다음과 같은 요청 시 반드시 이 스킬을 사용하세요:
- "<트리거 문장 1>"
- "<트리거 문장 2>"
metadata:
version: "0.1.0" # 사용자 메타데이터는 문자열 값
---
name과 description은 양쪽 호스트가 스킬을 찾을 때 쓰는 핵심 정보입니다. 버전은
metadata.version 문자열로 유지합니다. 설명은 1~1024자이며 이름은 디렉터리와 일치해야 합니다. user-invocable 같은 호스트별 필드는
공통 템플릿에 넣지 말고, 해당 호스트의 최신 문서와 실제 앱 동작을 확인한 뒤 결정합니다.
사용자 명령 진입점이 필요하다면 양쪽 호스트에서 각각 지원하는 방식을 확인합니다.
참고: OpenAI 스킬 작성, OpenAI 스킬 개념, Agent Skills 규격.
공통 형식
허용 최상위 필드는 name, description, license, compatibility, metadata, allowed-tools입니다. 추가 정보는 문자열 값의 metadata에 넣습니다.
- 최상위
version, 호스트 전용user-invocable keywords:(비표준)- 본문 상단
> vX.Y.Z | ...버전 배너
본문 구조 (필요한 섹션 선택)
# <Skill Name> — <한 줄 요약>
> <플러그인명> | <카테고리>
## 개요
스킬의 목적과 핵심 기능을 2-4문장으로 설명합니다.
어떤 문제를 해결하는지, 누가 사용하는지, 언제 사용하는지를 포함합니다.
## 트리거 키워드
<스킬 활성화 키워드를 공백으로 구분하여 나열>
예: 보고서 작성 리포트 생성 docx 워드 문서
## 워크플로우
단계별 실행 흐름을 번호와 함께 나열합니다:
1. [단계명] — 설명
2. [단계명] — 설명
3. [단계명] — 설명
## 실행 규칙
### 1단계: <단계명>
상세 실행 규칙을 작성합니다.
| 조건 | 동작 |
|------|------|
| 케이스 A | 결과 A |
| 케이스 B | 결과 B |
### 2단계: <단계명>
...
## 사용 예시
사용자가 복사-붙여넣기 할 수 있는 실제 프롬프트를 최소 2개 제공합니다.
**예시 1: 기본 사용**
> "<자연어 프롬프트>"
**예시 2: 고급 사용**
> "<자연어 프롬프트>"
## 출력 형식
스킬이 생성하는 산출물의 형식을 명시합니다.
| 산출물 | 형식 | 설명 |
|--------|------|------|
| <산출물1> | <포맷> | <설명> |
## 주의사항
- 스킬 사용 시 주의할 점
- 한계점 및 제약사항
- 대안 스킬 참조 (해당 시)
## 관련 스킬
| 스킬 | 관계 | 설명 |
|------|------|------|
| <연관 스킬> | <before/after/alternative> | <설명> |
복잡도 가이드
| 티어 | 대략적인 범위 | 권장 내용 | 검증 |
|---|---|---|---|
| Simple | 짧은 작업 | 목적, 실행 단계, 예시 | 실행 가능한 사례 확인 |
| Standard | 여러 단계 | 입력·출력, 오류 처리, 예시 | 정상·경계 사례 확인 |
| Complex | 여러 도구·서비스 | 단계 경계, 승인, 실패·재개 절차 | 실제 호스트에서 체인 검증 |
품질 체크리스트
작성 완료 후 반드시 확인:
-
name,description,metadata.version이 공통 규격을 만족함 -
skills-ref표준 검사와 저장소의 스킬 계약 검사를 통과함 - 작업을 실행하는 데 필요한 입력·단계·출력·실패 처리가 설명됨
- 실제 사용 상황에 맞는 예시가 있음
- 트리거 키워드가 다른 스킬과 중복되지 않음
- 워크플로우 단계가 순차적으로 실행 가능함
- 관련 스킬이 있다면 연결 관계를 명시함
- 플러그인에 넣는 경우 양쪽 매니페스트와 버전을 확인함
Source: revfactory/harness skill-writing-guide (Apache 2.0) + MoAI adaptation