--- title: "스킬" slug: "clovastudio-skill" tags: ["CLOVA Studio", "스킬", "스킬 트레이너"] updated: 2026-09-17T09:07:14Z published: 2026-09-17T09:07:14Z canonical: "guide.ncloud-docs.com/clovastudio-skill" stale: true --- > ## Documentation Index > Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # 스킬 Classic/VPC 환경에서 이용 가능합니다. 스킬은 사용자의 요구 사항에 정확하고 적절한 응답을 주기 위해 사용하는 도구입니다. 모델은 사용자의 질문과 스킬에 작성된 API를 분석하여 가장 적절한 답을 줄 수 있는 스킬을 선택한 후, 정확한 정보를 호출하여 사용자에게 제공할 수 있습니다. 스킬 트레이너에서 생성한 스킬은 다음과 같은 작업을 수행할 수 있습니다. - 실시간 정보 검색: 동물 병원 조회, 채용 공고 조회, 실시간 인기 상품, 실시간 차량 정보 - 지식 기반 정보 검색: 여행지 추천, 상품 추천, 여행 정보 ## 스킬 생성 스킬을 생성하는 방법은 다음과 같습니다. 1. 네이버 클라우드 플랫폼 콘솔에서 **Menu** > **All Services** > **AI Services** > **CLOVA Studio** 메뉴를 차례대로 클릭해 주십시오. 2. **My Product** 메뉴에서 **[CLOVA Studio 바로가기]** 버튼을 클릭해 주십시오. 3. CLOVA Studio에서 **스킬 트레이너** 메뉴를 클릭해 주십시오. 4. 스킬셋을 클릭해 주십시오. 5. 화면 오른쪽 상단의 **[스킬 생성]** 버튼을 클릭해 주십시오. 6. 스킬 정보 화면이 나타나면 스킬 이름을 입력한 후 **[중복 확인]** 버튼을 클릭해 주십시오. - 스킬 이름은 영문자, 한글, 숫자, 공백을 허용하며 20자 이내로 입력해 주십시오. - 해당 스킬셋 내에서 스킬 이름이 중복되지 않도록 입력해 주십시오. 7. API Spec 영역에 API 스펙을 JSON 타입의 OAS 3.0 버전으로 작성해 주십시오. - API Spec을 작성하는 방법은 [API Spec 작성](/docs/clovastudio-skill#APISpec%EC%9E%91%EC%84%B1)을 참조해 주십시오. 8. API 스펙 작성이 완료되면 **[검증하기]** 버튼을 클릭해 주십시오. - 검증 성공 시 'API Spec 검증이 완료되었습니다' 문구가 표시되고 **[검증하기]** 버튼이 비활성화됩니다. - 검증 실패 시 오류 메시지가 나타납니다. API 스펙을 다시 수정해 주십시오. 9. Manifest 영역에 정보를 입력해 주십시오. - Manifest를 작성하는 방법은 [Manifest 작성](/docs/clovastudio-skill#Manifest%EC%9E%91%EC%84%B1)을 참조해 주십시오. 10. **Name for model**의 **[중복 확인]** 버튼을 클릭해 주십시오. 11. 필수 정보를 모두 입력한 후, **[생성하기]** 버튼을 클릭해 주십시오. - 현재까지 작업한 내용을 저장하려면 **[임시 저장]** 버튼을 클릭해 주십시오. - 모든 영역이 입력되었더라도 **[임시 저장]** 버튼을 클릭하는 경우, 작업 상태가 '작업 중'으로 저장됩니다. 12. 스킬 생성 완료 창이 나타나면 **[확인]** 버튼을 클릭해 주십시오. 참고 하나의 스킬셋에 최대 10개의 스킬을 추가할 수 있습니다. ### API Spec 작성 API Spec 항목에는 모델이 이해할 수 있는 API 스펙을 작성합니다. 스킬 트레이너에서는 JSON 형식만 지원합니다. 자세한 명세는 [OpenAPI Specification v3.0.0](https://spec.openapis.org/oas/v3.0.0)을 참조해 주십시오. #### Version 사용할 OpenAPI 버전 정보입니다. 3.0 버전만 지원하며, 다른 버전을 사용할 경우 오류가 발생할 수 있습니다. 필수 입력 값입니다. 작성 예시는 다음과 같습니다. ``` { "openapi": "3.0.0" } ``` #### Info 제공되는 API에 관한 정보입니다. 필수 입력 값입니다. | 필드 | 설명 | 필수 여부 | | --- | --- | --- | | version | API 버전 정보 | Y | | title | API 이름 | Y | 작성 예시는 다음과 같습니다. ``` info: version: API 버전 title: API 제목 description: API 설명 contact: API 제공자 license: API 라이선스 정보 ``` #### Servers API가 제공되는 대상 호스트 정보로 Path들의 baseURL입니다. 필수 입력 값입니다. | 필드 | 설명 | 필수 여부 | | --- | --- | --- | | url | 서버 URL | Y | 작성 예시는 다음과 같습니다. ``` servers: - url: https://sample.naver.com/v1 ``` #### Paths 제공되는 API의 각 Path 정보입니다. 필수 입력 값입니다. 각 Path의 하위에는 Operation Object와 Parameter Object가 존재합니다. | 필드 | 설명 | 필수 여부 | | --- | --- | --- | | Summary I Description | 사용할 파라미터와 해당 Path를 통해 얻을 수 있는 정보를 구체적으로 작성 <예시> 여행지의 국내외 여부, 지역명, 방문하는 달, 여행자 수, 예상 경비를 통해서 여행 지역 및 도시 검색 | Y | 참고 - requests get, requests post 메소드만 지원합니다. - POST 메소드인 경우, 'nested datatype'은 아직 정식 지원하지 않으므로 파라미터를 분리해서 작성해 주십시오. - URL은 반드시 argument 방식으로 동작하는 것으로 가정하여 작성해 주십시오. 현재의 모델은 argument 방식만 지원합니다. (파라미터=파라미터의 값) <예시 1> http://test.com/data?birthdata=20190302&address=서초구 (O) <예시 2 > http://test.com/data?20190302/서초구 (X) 작성 예시는 다음과 같습니다. ``` paths: /test: get: description: get test data (해당 path가 어떤 상황에서 쓰이는지 구체적으로 작성) operationId: getTest responses: '200': description: test response content: application/json: schema: type: array items: $ref: '#/components/schemas/Test' ``` #### Parameter Object 작업에 적용할 수 있는 매개 변수 목록입니다. 필수 입력 값입니다. | 필드 | 설명 | 필수 여부 | | --- | --- | --- | | name | 매개 변수의 이름. 대소문자 구별 | Y | | in | 매개 변수의 위치. - 사용 가능한 값: query | Y | | description | 해당 파라미터에 대한 구체적인 설명 | N | | required | 매개 변수의 필수 여부 결정 - 사용 가능한 값: true, false | N | | schema: type | 매개변수 데이터 유형 설정 - 사용 가능한 값: string, integer, number, boolean, array | N | | schema:format | 데이터 타입별 포맷 설정 - 데이터 타입별 설정 가능한 포맷은 [OpenAPI Specification v3.0.0](https://spec.openapis.org/oas/v3.0.0) 참조 | N | 참고 description에는 해당 파라미터가 어떤 의미를 갖고 있는지, 어떤 상황에서 사용되는 것인지, URL 생성 시 어떤 형식으로 들어가야 하는지 등을 구체적으로 작성합니다. 만약 파라미터가 가져야 하는 값이 한정되어 있다면 예시 값을 구체적으로 작성합니다. - male 또는 female 둘 중 하나의 값만 가져야 한다면 description에 구체적으로 작성합니다. <예시> male 또는 female 중에 하나 - 강남으로 검색해도 강남구로 url에 들어가야 한다면 description에 구체적으로 작성합니다. <예시> 강남구, 서초구 - 해당 파라미터가 한정된 장소를 검색하는 값이라면, 단순 검색어가 아닌 '레스토랑 또는 카페와 같은 특정 장소를 검색할 때 사용된다'라는 의미를 모델이 이해할 수 있도록 작성합니다. <예시> ``` { "parameters": [ { "name": "place_category", "in":"query", "description": "장소의 대분류. restaurant, cafe, attraction, accommodation 중에 하나.", "required": false, "schema": { "type": "string" } } ] } ``` 작성 예시는 다음과 같습니다. ``` parameters: - name: birthdate in: query description: 생일을 의미합니다. 입력 형식은 yyyy-mm-dd입니다. required: true schema: type: array style: simple items: type: string format: date ``` #### Operation Object API 호출 작업에 대한 정보입니다. 필수 입력 값입니다. | 필드 | 설명 | 필수 여부 | | --- | --- | --- | | description | 작업 동작에 대한 자세한 설명 | N | | operationId | 작업 식별 시 사용되는 고유 문자열. Open API를 이용하는 다른 툴이나 라이브러리에서 operationId를 사용하여 식별하는 것도 가능 | Y | | responses | 작업을 실행하여 반환되는 것이 가능한 응답 목록. 응답은 Response Object 형태로 제공 | Y | 작성 예시는 다음과 같습니다. ``` get: description: get test data operationId: getTest responses: '200': description: teset response content: application/json: schema: type: array items: $ref: '#/components/schemas/Test' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' ``` #### Response Object 작업 응답에 대한 설명입니다. 필수 입력 값입니다. | 필드 | 설명 | 필수 여부 | | --- | --- | --- | | description | 응답에 대한 간단한 설명 | Y | 참고 200 응답은 필수 값이며, HTTP 상태 코드에 따라 기타 응답을 추가할 수 있습니다. - 잘못된 파라미터에 대한 요청 시 422, 400 오류를 반환합니다. - 정의된 오류 코드가 없을 경우, 422 오류를 임의로 만들어서 반환합니다. 작성 예시는 다음과 같습니다. ``` responses: '200': description: test response content: application/json: schema: items: $ref: '#/components/schemas/Test' default: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' ``` #### Components OAS의 다양한 부분에서 재사용 가능한 객체 집합입니다. | 필드 이름 | 타입 | 설명 | | --- | --- | --- | | schemas | Map[string, [Schema Object](https://spec.openapis.org/oas/v3.0.0#schemaObject) I [Reference Object](https://spec.openapis.org/oas/v3.0.0#referenceObject)] | 재사용 가능한 Schema Object의 객체 | | responses | Map[string, [Response Object](https://spec.openapis.org/oas/v3.0.0#responseObject) I [Reference Object](https://spec.openapis.org/oas/v3.0.0#referenceObject)] | 재사용 가능한 Response Object의 객체 | | parameters | Map[string, [Parameter Object](https://spec.openapis.org/oas/v3.0.0#parameterObject) I [Reference Object](https://spec.openapis.org/oas/v3.0.0#referenceObject)] | 재사용 가능한 Parameter Object의 객체 | | examples | Map[string, [Example Object](https://spec.openapis.org/oas/v3.0.0#exampleObject) I [Reference Object](https://spec.openapis.org/oas/v3.0.0#referenceObject)] | 재사용 가능한 Example Object의 객체 | 작성 예시는 다음과 같습니다. ``` components: schemas: Test: allOf: - $ref: '#/components/schemas/NewTest' - type: object required: - id properties: id: type: integer format: int64 example: 100 NewTest: type: object required: - name properties: name: type: string tag: type: string example: "test tag" ``` ### API Spec 확장 기능 API Spec에서 x-exclude-cot 객체를 사용하면 API 응답에서 해당 파라미터를 제외할 수 있습니다. Response Object에서 사용되고, Content-Type이 application/json 타입인 경우에만 적용 가능합니다. 응답에 사용되는 모든 매개 변수를 정확하게 작성해야 정상적으로 적용됩니다. x-exclude-cot 객체는 다음과 같은 경우에 활용할 수 있습니다. - API 응답이 길어서 토큰 수 초과 에러가 발생하는 경우 x-exclude-cot가 적용된 파라미터의 경우 데이터 수집 과정 중 'API 호출 결과'에서 제외됩니다. 따라서 실제 사용되지 않는 파라미터에 x-exclude-cot를 적용하면 데이터 수집 시 API 응답을 줄일 수 있습니다. - 학습 비용을 절약하고자 하는 경우 불필요한 파라미터에 x-exclude-cot를 적용하면, 데이터 수집 과정에서 토큰 수를 절약할 수 있습니다. 결과적으로 학습에 사용되는 토큰 수를 절약할 수 있습니다. API 응답에서 address라는 매개 변수를 제외하도록 설계한 예시는 다음과 같습니다. ``` "responses": { "200": { "description": "test response", "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "address": { "type": "object", "properties": { "city" : { "type": "string" }, "state": { "type": "string" } }, "x-exclude-cot": true }, "contact": { "type": "string" } } } } } } } ``` 참고 데이터 수집이 아닌, 테스트 앱이나 서비스 앱을 발급하여 호출하는 경우에는 x-exclude-cot가 적용된 필드도 API 응답에 모두 노출됩니다. 이 경우 API 응답에 대한 토큰 수 초과 에러는 발생되지 않습니다. ### API Spec 작성 예시 API Spec 작성 예시를 설명합니다. #### Requests_get을 사용하는 예시 Requests_get을 사용하는 예시는 다음과 같습니다. ``` { "openapi": "3.0.0", "info": { "version": "v0", "title": "국내 항공기 운행 스케줄 검색" }, "servers": [ { "url": "http://test.airport.co.kr/service/rest/TestFlightScheduleList" } ], "tags": [ { "name": "open-ai-product-endpoint", "description": "Open AI Product Endpoint. Query for products." } ], "paths": { "/getDflightScheduleList": { "get": { "tags": [ "open-ai-product-endpoint" ], "summary": "국내 항공기 운행 스케줄을 검색합니다.", "operationId": "productsUsingGET", "parameters" : [ { "name" : "serviceKey", "in" : "query", "description" : "serviceKey는 반드시 2FMD를 쓰세요", "required" : true, "schema" : { "type" : "string", "default" : "1" }}, { "name" : "schDate", "in" : "query", "description" : "검색 일자. 반드시 8자리의 숫자로 입력하세요. 예를 들어 2022년 4월 1일이면 20220401", "required" : false, "schema" : { "type" : "string" } }, { "name" : "schDeptCityCode", "in" : "query", "description" : "도착 도시 코드. 예를 들어 서울을 나타내는 GMP를, 도착도시코드는 제주도를 나타내는 CJU, 부산은 PSU", "required" : false, "schema" : { "type" : "string", "default" : "10" } }, { "name" : "schArrvCityCode", "in" : "query", "description" : "출발 도시 코드. 예를 들어 서울을 나타내는 GMP를, 도착도시코드는 제주도를 나타내는 CJU, 부산은 PSU", "required" : false, "schema" : { "type" : "string", "default" : "10" } } ], "responses": { "200": { "description": "Products found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rss" } } } }, "503": { "description": "one or more services are unavailable" } }, "deprecated": false } } }, "components": { "schemas": { "Rss": { "type": "object", "properties": { "airlineKorean": { "type": "string", "description": "항공사(국문)" }, "arrivalcity": { "type": "string", "description": "도착 공항" }, "domesticArrivalTime": { "type": "integer", "description": "도착 시간" }, "domesticEddate": { "type": "string", "format": "date-time", "description": "" }, "domesticFri": { "type": "string", "description": "금요일" }, "domesticMon": { "type": "string", "description": "월요일" }, "domesticNum": { "type": "string", "description": "항공편명" }, "domesticSat": { "type": "string", "description": "토요일" }, "domesticStartTime": { "type": "integer", "description": "출발 시간" }, "domesticStdate": { "type": "string", "format": "date-time", "description": "" }, "domesticSun": { "type": "string", "description": "일요일" }, "domesticThu": { "type": "string", "description": "목요일" }, "domesticTue": { "type": "string", "description": "화요일" }, "domesticWed": { "type": "string", "description": "수요일" }, "startcity": { "type": "string", "description": "출발 공항" }, "numOfRows": { "type": "integer", "description": "열 숫자" }, "pageNo": { "type": "integer", "description": "페이지 번호" }, "totalCount": { "type": "integer", "description": "데이터 총계" } } } } } } ``` #### Requests_post를 사용하는 예시 Requests_post를 사용하는 예시는 다음과 같습니다. ``` { "openapi": "3.0.0", "info": { "title": "Free API Documentation", "version": "1.0.0" }, "servers": [ { "url": "https://test.bakery.com" } ], "paths": { "/bakery_products": { "post": { "summary": "베이커리 제품 정보를 등록하는 API입니다.", "description": "베이커리 제품 정보를 등록하는 API입니다.", "operationId": "filterBakeryProducts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "제품 영문명" }, "max_price": { "type": "integer", "description": "최대 가격 (원)" }, "ingredients": { "type": "string", "description": "재료의 영문명" }, "expiration_date": { "type": "string", "description": "유통 기한. 예시) 20220701" }, "allergens": { "type": "string", "description": "알레르기 성분의 영문명" } }, "required": [ "max_price" ] } } } }, "responses": { "200": { "description": "성공적인 응답", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "제품 ID" }, "name": { "type": "string", "description": "제품 이름" }, "price": { "type": "integer", "description": "가격 (원)" }, "ingredients": { "type": "array", "items": { "type": "string" }, "description": "재료 목록" }, "expiration_date": { "type": "string", "format": "date", "description": "유통 기한" }, "calories": { "type": "integer", "description": "칼로리" }, "allergens": { "type": "array", "items": { "type": "string" }, "description": "알레르기 성분 목록" }, "additional_options": { "type": "array", "items": { "type": "string" }, "description": "추가 옵션 목록" } } } } } } } } } } } } ``` ### Manifest 작성 Manifest는 해당 스킬을 통해 호출할 수 있는 API의 이름, 목적, 사용 방법 등을 입력하는 영역입니다. Manifest의 입력 영역인 Name for model, Description for human, Description for model 각 필드에 대해 설명합니다. - **Name for model** - 모델 이름을 작성합니다. 다른 API와 이름이 중복되지 않아야 하며 API의 성격을 내포하여 간결하게 작성해야 합니다. - 영문자, 숫자를 허용하며 대문자로 시작하는 문자열을 20자 이내로 입력해 주십시오. 한글, 특수 문자, 공백을 허용하지 않습니다. - 두 개 이상의 단어를 조합할 경우, 각 단어의 첫 글자은 대문자로 작성해 주십시오. 예를 들어, 'animal'과 'hospital'이라는 두 개의 단어를 조합하여 API 이름을 만들 경우 'AnimalHospital'라고 작성합니다. - 스킬 이름에 'API'라는 단어는 사용하지 마십시오. - **Description for human** - API의 목적과 용도를 작성합니다. 모든 API의 역할이 명확하게 작성되어야 합니다. 사용자의 질문을 바탕으로 모델이 여러 API 중에서 필요한 API를 선택하는 기준이 됩니다. - 예를 들어 동물병원 검색, 애견카페 검색, 애견용품 검색 API가 존재할 때 사용자의 질문이 '동물병원 위치 알려줘'일 경우, 모델은 각 API의 description_for_human을 읽고 동물병원 검색 API를 선택합니다. - 작성 예시는 다음과 같습니다. ``` 울산광역시에 있는 동물 병원을 찾을 때 사용합니다. 병원 이름으로 조회하여 동물 병원의 주소와 연락처 정보를 제공합니다. ``` - **Description for model** - API의 주요 사용 방법을 5,000자 이내로 작성합니다. 모델이 사용자의 질문에 답변할 때 사용할 API를 결정할 때 사용자의 질문과 ‘decription_for_model’을 모두 참고하여 여러 개의 API 중 적절한 API를 선택합니다. 또한 API 응답으로 받을 수 있는 정보에 대해서도 작성해야 합니다. 각 API를 호출했을 때 어떤 정보를 받을 수 있는지에 대해 범위를 상세하게 작성해야 모델이 API를 적절하게 선택하여 사용할 수 있습니다. 만약 Path가 여러 개인 경우에는 Path별 역할에 대해 자세히 작성해야 합니다. Path별로 검색되어야 할 키워드를 작성해야 모델이 해당 API를 적절하게 사용할 수 있습니다. - 작성 예시는 다음과 같습니다. ``` 전통 시장의 정보와 주차장 시설 정보를 조회하는 API입니다. 이 API를 호출하면 응답으로 장소명, 주소, 운영 시간 정보가 제공됩니다. 서울시 전통 시장의 정보를 알고 싶을 때에는 /traditional_market을 사용하세요. /traditional_market은 시장 이름, 영업일, 휴무일, 주소 키워드, 영업 시작 시간, 영업 종료 시간을 검색어로 입력할 때 동작합니다. 주차장 시설 정보를 얻고 싶을 때는 /parking_lot을 사용하세요. /parking_lot은 지역구분_구, 지역구분_동, 주차장 명, 주차장 종류, 운영시간, 최소 가격을 검색어로 입력할 때 동작합니다. 전송할 쿼리에는 관사, 전치사, 결정자와 같은 중지어가 포함되어서는 안 됩니다. 링크는 항상 반환되며 사용자에게 표시되어야 합니다. ``` ``` 울산광역시 동물 병원 현황 조회 API입니다. 이 API를 호출하면 응답으로 동물 병원 이름, 위치, 전화번호, 운영 시간 정보가 제공됩니다. 울산시에 있는 동물 병원을 검색할 때는 /getPetHospitalList를 사용하세요. /getPetHospitalList는 판매점 이름을 검색어로 입력할 때 동작합니다. 전송할 쿼리에는 관사, 전치사, 결정자와 같은 중지어가 포함되어서는 안 됩니다. 링크는 항상 반환되며 사용자에게 표시되어야 합니다. ``` ## 스킬 편집 스킬 정보를 편집하는 방법은 다음과 같습니다. 1. 네이버 클라우드 플랫폼 콘솔에서 **Menu** > **All Services** > **AI Services** > **CLOVA Studio** 메뉴를 차례대로 클릭해 주십시오. 2. **My Product** 메뉴에서 **[CLOVA Studio 바로가기]** 버튼을 클릭해 주십시오. 3. CLOVA Studio에서 **스킬 트레이너** 메뉴를 클릭해 주십시오. 4. 스킬셋을 클릭해 주십시오. 5. **스킬** 탭을 클릭한 후 편집할 스킬명을 클릭해 주십시오. 6. 스킬 정보를 수정한 후, **[저장하기]** 버튼을 클릭해 주십시오. - 수정한 내용이 있거나 필수 항목이 모두 작성되어야 **[저장하기]** 버튼이 활성화됩니다. - 스킬 이름과 Name for model을 수정한 경우, **[중복 확인]** 버튼을 클릭해 주십시오. - API Spec을 수정한 경우, **[검증하기]** 버튼을 클릭해 주십시오. 7. 편집할 내용이 없으면 **[취소]** 버튼을 클릭해 주십시오. ## 스킬 삭제 스킬을 삭제하는 방법은 다음과 같습니다. 1. 네이버 클라우드 플랫폼 콘솔에서 **Menu** > **All Services** > **AI Services** > **CLOVA Studio** 메뉴를 차례대로 클릭해 주십시오. 2. **My Product** 메뉴에서 **[CLOVA Studio 바로가기]** 버튼을 클릭해 주십시오. 3. CLOVA Studio에서 **스킬 트레이너** 메뉴를 클릭해 주십시오. 4. 스킬셋을 클릭해 주십시오. 5. **스킬** 탭을 클릭해 주십시오. 6. 삭제할 스킬의 ⋮ > **삭제** 메뉴를 클릭해 주십시오. 7. 삭제 팝업 창이 나타나면 **[삭제]** 버튼을 클릭해 주십시오.