> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloosphere.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 스킬

> 에이전트가 스스로 불러 따르는 재사용 지침서(playbook)를 만들고, 문서 생성 같은 반복 작업을 표준화합니다

스킬(Skill)은 **에이전트가 스스로 골라 실행하는 재사용 지침서**입니다.
"이런 요청이 오면 이렇게 처리하라"는 방법(playbook)을 한 번 정의해 두면, 에이전트가 대화 중 요청이 그 스킬의 용도와 맞을 때 자동으로 불러와 그대로 따릅니다.

```mermaid theme={null}
flowchart LR
    A[사용자 요청] --> B[에이전트가 스킬 카탈로그 확인<br/>이름 + 언제 쓰는지]
    B --> C{요청과 맞는<br/>스킬이 있나?}
    C -->|No| D[일반 지식으로 응답]
    C -->|Yes| E[스킬 본문 불러오기]
    E --> F[지침을 그대로 수행]
    F --> G[답변 · 결과물]
```

<Note>
  스킬 탭은 현재 **미리보기(preview)** 단계로, 일부 환경(개발/스테이징 호스트)에서만 표시됩니다.
  운영 환경에서 스킬 탭이 보이지 않는다면 관리자에게 문의하세요. 문서 생성 스킬(PPT·Word·Excel·HTML)은 [마켓플레이스](/ko/workspace/marketplace)를 통해 제공됩니다.
</Note>

***

## 스킬이란?

스킬은 에이전트에게 전달하는 **명령형 지침서**입니다. 세 가지 요소로 구성됩니다.

| 요소                | 역할                          |
| ----------------- | --------------------------- |
| **이름**            | 스킬 식별자 (전역에서 고유)            |
| **설명 (언제 쓰는지)**   | 에이전트가 이 스킬을 언제 사용할지 판단하는 기준 |
| **본문 (SKILL.md)** | 에이전트가 따라야 할 단계별 지침          |

여기에 필요하면 **번들 파일**(스크립트, 참고 문서 등)을 함께 담을 수 있습니다.

### 스킬 vs 프롬프트

혼동하기 쉽지만 정반대의 도구입니다.

<Columns cols={2}>
  <Card title="프롬프트" icon="message">
    **사람이 직접 타이핑**해서 부릅니다. 채팅에서 `/` 명령어로 저장된 텍스트를 펼칩니다.
  </Card>

  <Card title="스킬" icon="wand-magic-sparkles">
    **에이전트가 스스로 선택**합니다. 사용자는 스킬을 호출하지 않습니다 — 요청이 설명과 맞으면 에이전트가 알아서 불러 씁니다.
  </Card>
</Columns>

<Tip>
  그래서 **설명("언제 쓰는지")을 잘 쓰는 것이 가장 중요합니다.** 에이전트는 오직 이 설명을 보고 스킬을 발동할지 판단합니다.
  예: "사용자가 회의록을 표준 양식으로 정리해 달라고 할 때 사용합니다."
</Tip>

***

## 스킬 목록

**워크스페이스 > 스킬**에서 접근 가능한 모든 스킬을 확인합니다.

각 카드에는 이름, 설명, 작성자, 마지막 수정 시각이 표시됩니다. 상단 검색창으로 이름·설명을 검색할 수 있고, 우측 상단에 **AI로 생성**과 **새 스킬** 버튼이 있습니다(스킬 쓰기 권한이 있는 경우).

카드의 동작:

| 동작        | 설명                       |
| --------- | ------------------------ |
| **카드 클릭** | 편집 화면으로 이동 (수정 권한이 있을 때) |
| **내보내기**  | 스킬을 JSON 파일로 다운로드        |
| **삭제**    | 소유자 또는 관리자만 가능           |

<Warning>
  **내보내기(Export)는 부분 백업입니다.** 이름·설명·본문만 담기며, 번들 파일과 접근 권한 설정은 포함되지 않습니다. 완전한 백업 수단으로 사용하지 마세요.
</Warning>

***

## 스킬 만들기

스킬을 만드는 방법은 두 가지입니다.

<Tabs>
  <Tab title="새 스킬 (직접 작성)">
    **새 스킬** 버튼을 누르면 먼저 기본 정보를 입력합니다.

    | 필드                                | 설명                        |
    | --------------------------------- | ------------------------- |
    | **어떤 작업을 하고 계신가요?** (이름)          | 스킬 이름                     |
    | **에이전트가 이 스킬을 언제 사용해야 하나요?** (설명) | 발동 조건                     |
    | **권한**                            | 비공개 / 공개, 그룹·조직 단위별 읽기/쓰기 |

    저장하면 곧바로 **편집기**로 이동해 본문(SKILL.md)을 작성합니다. 직접 만든 스킬은 기본적으로 **비공개**(소유자 전용)입니다.
  </Tab>

  <Tab title="AI로 생성">
    **AI로 생성** 버튼을 누르고, 원하는 스킬을 자연어로 설명한 뒤 모델을 선택합니다.

    ```
    예: 파이썬 코드를 리뷰하고 성능 개선을 제안하는 스킬
    ```

    AI가 스킬의 **이름·설명·본문 초안**을 작성해 줍니다. 생성 후 편집기로 이동하니 검토·수정하세요.

    <Warning>
      \*\*AI로 생성한 스킬은 기본적으로 공개(Public)\*\*로 저장됩니다 — 로그인한 모든 사용자가 읽을 수 있습니다.
      비공개로 두려면 편집기의 **접근** 버튼에서 권한을 변경하세요.
    </Warning>
  </Tab>
</Tabs>

<Note>
  스킬 **이름은 전체 워크스페이스에서 고유**해야 하며 대소문자를 구분합니다. 이미 있는 이름으로 저장하면 오류가 납니다.
</Note>

***

## 스킬 편집기

편집기는 좌측 **파일 트리**와 우측 **편집 영역**으로 구성된 작은 IDE입니다.

### 진입점 — SKILL.md

`SKILL.md`는 항상 파일 트리 맨 위에 **진입점(Entry)** 태그와 함께 표시됩니다. 이 파일의 내용이 스킬 본문이며, 에이전트가 스킬을 발동하면 따르는 지침입니다.

<Tip>
  본문은 **에이전트에게 지시하는 명령형**으로 쓰세요. 단계별 절차, 지켜야 할 규칙, 출력 형식을 구체적으로 적을수록 에이전트가 일관되게 따릅니다.
</Tip>

### 번들 파일 추가

파일 트리의 **+ 파일 추가** 버튼으로 스크립트나 참고 문서를 추가합니다. 경로를 지정하면(예: `scripts/lookup.py`, `references/style-guide.md`) 폴더별로 정리됩니다.

* 마크다운 파일은 서식 툴바(굵게/기울임/코드/목록)와 **편집/미리보기** 전환을 지원합니다
* 코드 파일(`.py`, `.js`, `.sql` 등)은 문법 강조가 적용됩니다
* 경로는 상대 경로만 허용되며 `SKILL.md`는 번들 파일로 쓸 수 없습니다(진입점 전용)

<Note>
  본문이 번들 파일을 참조하면, 에이전트는 필요할 때만 해당 파일을 읽습니다. 모든 파일을 한꺼번에 읽지 않으므로 큰 참고 자료도 부담 없이 담을 수 있습니다.
</Note>

### 메타 정보

편집기 상단 메타 영역에서 두 가지를 확인할 수 있습니다.

| 항목          | 의미                           |
| ----------- | ---------------------------- |
| **사용 에이전트** | 이 스킬을 사용하는 에이전트 목록 (역방향 의존성) |
| **가져옴**     | 마켓플레이스·번들 등 외부에서 가져온 스킬 표시   |

<Tip>
  스킬을 삭제하거나 크게 바꾸기 전에 **사용 에이전트**를 확인하세요. 사용 중인 스킬을 삭제하려 하면 확인 절차를 거칩니다.
</Tip>

***

## 에이전트에 연결

스킬은 에이전트에 연결해야 동작합니다.

<Steps>
  <Step title="에이전트 편집 화면 열기">
    **워크스페이스 > 에이전트**에서 편집할 에이전트를 엽니다.
  </Step>

  <Step title="스킬 섹션에서 선택">
    **스킬** 섹션에서 연결할 스킬을 추가합니다. 마켓플레이스 문서 생성기 인스턴스도 여기에서 함께 선택합니다.
  </Step>

  <Step title="저장">
    저장하면 에이전트가 해당 스킬들을 사용할 수 있게 됩니다.
  </Step>
</Steps>

<Note>
  스킬에는 별도의 켜기/끄기 토글이 없습니다. **에이전트에 연결하면 켜지고, 연결을 해제하면 꺼집니다.** 채팅 중 개별 토글은 없습니다.
</Note>

***

## 채팅에서 동작 방식

에이전트에 스킬이 연결되면, 채팅 중 다음 순서로 동작합니다.

1. 에이전트는 연결된 스킬들의 **이름 + 설명** 목록을 항상 인지합니다
2. 사용자 요청이 어떤 스킬의 설명과 맞으면, 그 스킬의 **본문을 불러옵니다**
3. 지침을 따라 작업을 수행합니다 (필요 시 번들 파일을 읽거나 스크립트를 실행)
4. 결과를 답변에 반영합니다

<Note>
  스킬 발동은 **화면에 별도 표시가 없습니다.** 에이전트가 조용히 지침을 따를 뿐입니다. 단, 문서 생성 스킬처럼 파일을 만드는 경우 답변 위에 **`📎 다운로드: [파일명](링크)`** 형태로 결과 파일이 먼저 표시됩니다.
</Note>

***

## 실행형 스킬과 문서 생성

일부 스킬은 번들된 스크립트를 실제로 **실행**해 파일(PPT·Word·Excel·HTML 등)을 만들 수 있습니다. 이런 **실행형 스킬**은 다음 조건에서만 동작합니다.

* 스킬이 실행형으로 표시되어 있어야 합니다 (마켓플레이스 문서 생성기가 대표적)
* 관리자가 **코드 실행 엔진(Jupyter)** 을 설정해 두어야 합니다

<Warning>
  코드 실행 엔진이 설정되지 않으면, 실행형 스킬은 스크립트를 돌리지 못하고 지침만 따르게 되어 **파일이 생성되지 않습니다.** 문서 생성 기능이 동작하지 않으면 관리자에게 코드 실행 설정을 확인하세요.
</Warning>

직접 작성한 스킬은 실행형이 될 수 없습니다. 실행형 문서 생성 기능이 필요하면 [마켓플레이스](/ko/workspace/marketplace)의 문서 생성기를 사용하세요.

***

## 접근 권한

스킬은 다른 워크스페이스 리소스와 동일한 권한 체계를 따릅니다.

| 옵션                | 설명                                     |
| ----------------- | -------------------------------------- |
| **공개 (Public)**   | 로그인한 모든 사용자가 읽을 수 있음                   |
| **비공개 (Private)** | 소유자와 관리자만. 특정 그룹·조직 단위에 읽기/쓰기 권한 부여 가능 |

<Note>
  에이전트가 스킬을 사용할 때는 **실행하는 사용자의 읽기 권한**으로 다시 확인합니다. 비공개 스킬이 공유 에이전트에 연결돼 있어도, 읽기 권한이 없는 사용자에게는 노출·발동되지 않습니다.
</Note>

관리자는 **관리자 설정 > 사용자 > 그룹**에서 그룹별 **스킬 접근** 권한(없음/읽기/쓰기)을 제어합니다. 기본값은 잠금(없음)입니다.

***

## 트러블슈팅

<AccordionGroup>
  <Accordion title="스킬 탭이 보이지 않아요" icon="eye-slash">
    | 원인         | 해결 방법                             |
    | ---------- | --------------------------------- |
    | 미리보기 환경 제한 | 스킬 탭은 일부 환경에서만 노출됩니다. 관리자에게 문의하세요 |
    | 권한 없음      | 관리자에게 그룹의 **스킬 접근** 권한 부여를 요청하세요  |
  </Accordion>

  <Accordion title="이름 저장이 안 돼요" icon="triangle-exclamation">
    스킬 이름은 워크스페이스 전체에서 고유해야 합니다. 다른 이름을 사용하세요. (대소문자를 구분합니다.)
  </Accordion>

  <Accordion title="문서(PPT 등)가 만들어지지 않아요" icon="file-slash">
    실행형 스킬은 관리자가 코드 실행 엔진(Jupyter)을 설정해야 동작합니다. **관리자 설정 > 마켓플레이스** 또는 **코드 실행** 설정을 확인하세요.
  </Accordion>

  <Accordion title="스킬을 삭제할 수 없어요" icon="lock">
    사용 중인 에이전트가 있으면 삭제가 차단됩니다. 편집기의 **사용 에이전트** 목록을 확인하고, 그래도 삭제하려면 강제 삭제 확인을 진행하세요.
  </Accordion>
</AccordionGroup>

***

## FAQ

<AccordionGroup>
  <Accordion title="스킬과 지식기반은 무엇이 다른가요?" icon="circle-question">
    지식기반(RAG)은 **사실 정보**를 검색해 제공합니다. 스킬은 **작업 방법·절차**를 제공합니다. 둘은 함께 쓸 수 있습니다 — 예를 들어 스킬이 "이 양식으로 정리하라"고 지시하고, 지식기반이 그 내용을 채웁니다.
  </Accordion>

  <Accordion title="스킬 본문은 얼마나 길게 써도 되나요?" icon="circle-question">
    권장은 500줄 이내입니다. 긴 참고 자료는 본문에 넣지 말고 **번들 파일**로 분리한 뒤 본문에서 참조하세요. 에이전트가 필요할 때만 읽습니다.
  </Accordion>

  <Accordion title="같은 스킬을 여러 에이전트가 써도 되나요?" icon="circle-question">
    네. 하나의 스킬을 여러 에이전트에 연결할 수 있습니다. 편집기의 **사용 에이전트**에서 현재 어떤 에이전트가 쓰는지 확인할 수 있습니다.
  </Accordion>

  <Accordion title="AI로 생성한 스킬을 바로 써도 되나요?" icon="circle-question">
    초안이므로 반드시 검토하세요. 특히 기본 공개(Public)로 저장되니, 필요하면 접근 권한을 비공개로 바꾸고 본문을 다듬은 뒤 사용하세요.
  </Accordion>
</AccordionGroup>

***

## 다음 단계

<Columns cols={2}>
  <Card title="마켓플레이스" icon="store" href="/ko/workspace/marketplace">
    PPT·Word·Excel·HTML 문서 생성기와 Google Workspace·Microsoft 365 연동을 설정합니다
  </Card>

  <Card title="에이전트에 연결" icon="robot" href="/ko/workspace/agents">
    스킬을 에이전트에 연결하여 작업 방식을 표준화합니다
  </Card>
</Columns>