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

# Skill Format

> 에이전트가 안정적으로 따르는 SKILL.md 파일 작성 — 파일 구조, 프론트매터 필드, 지시 패턴

Skill은 단일 `SKILL.md` 파일입니다: 메타데이터를 위한 YAML 프론트매터, 에이전트가 따르는 지시가 담긴 Markdown 본문. 이 페이지는 해당 형식에 대한 레퍼런스입니다 — 구조, 프론트매터 필드, 에이전트가 가장 안정적으로 적용하는 지시 패턴.

## 파일 구조

모든 skill은 동일한 형태를 따릅니다 — 프론트매터 먼저, 그 다음 Markdown 헤딩으로 이루어진 지시 섹션:

```markdown theme={null}
---
name: security-review-checklist          # 슬러그 형식: 소문자, 하이픈
description: Enforce OWASP checks in code review   # skill 카드에 표시됨
---

## SQL injection                         # 규칙 그룹당 H2 하나

- Flag raw string concatenation in SQL queries
- Require parameterized queries or ORM methods

## Secrets handling

- Flag hardcoded credentials, tokens, and API keys
- Require secrets to come from a secrets manager or environment variables
```

| 부분       | 필수 여부 | 목적                                          |
| -------- | ----- | ------------------------------------------- |
| 프론트매터 블록 | 예     | skill을 식별하며, UI가 `name`과 `description`을 읽어옴 |
| 지시 본문    | 예     | skill 실행 시 에이전트가 그대로 로드하는 Markdown          |
| H2 규칙 그룹 | 권장    | 도메인당 하나의 헤딩으로 여러분과 에이전트가 규칙을 쉽게 파악          |
| 인라인 예시   | 권장    | 각 규칙을 뒷받침하는 구체적인 좋은/나쁜 예시                   |

## 프론트매터 필드

| 필드            | 필수 여부 | 설명                                                               |
| ------------- | ----- | ---------------------------------------------------------------- |
| `name`        | 예     | 슬러그 형식의 고유 식별자 (소문자, 하이픈, 공백 없음). 예: `security-review-checklist` |
| `description` | 예     | skill이 하는 일의 짧은 요약. UI의 skill 카드에 표시됩니다.                         |

## 효과적인 지시 작성

### 모든 토큰이 중요합니다

에이전트는 skill 지시를 자체 시스템 프롬프트 및 작업 컨텍스트와 함께 처리합니다. 지시를 간결하게 유지하세요 — 에이전트가 이미 알고 있는 내용은 작성하지 마세요.

```markdown theme={null}
<!-- 너무 장황함 -->
When reviewing code, you should always check for SQL injection
vulnerabilities. SQL injection is a type of security vulnerability
where an attacker can execute arbitrary SQL commands through
user input that is not properly sanitized...

<!-- 효과적 -->
## SQL Injection
- Flag raw string concatenation in SQL queries
- Require parameterized queries or ORM methods
- Check for `execute()` calls with f-strings or `.format()`
```

### 자유도 설정

에이전트가 가져야 할 유연성의 정도에 맞게 지시 스타일을 조정하세요:

| 자유도    | 스타일          | 사용 사례                      |
| ------ | ------------ | -------------------------- |
| **높음** | 가이드라인과 원칙    | 창의적인 작업, 아키텍처 조언, 탐색적 리뷰   |
| **중간** | 예시가 있는 체크리스트 | 표준 코드 리뷰, 보안 감사, 컴플라이언스 점검 |
| **낮음** | 정확한 템플릿과 규칙  | 규제 컴플라이언스, 형식 표준, 필수 필드    |

### 예시가 설명보다 낫습니다

에이전트는 추상적인 규칙보다 구체적인 예시를 더 안정적으로 따릅니다. 가능하면 설명하는 대신 기대하는 동작을 보여주세요.

```markdown theme={null}
## Naming conventions

Use descriptive variable names that reveal intent.

### Good
- `remaining_retries` not `r`
- `is_authenticated` not `auth`
- `max_connection_pool_size` not `pool`

### Bad
- Single-letter variables outside loop iterators
- Abbreviations that aren't universally understood
- Boolean variables without `is_`, `has_`, or `should_` prefix
```

## 전체 예제

PR 리뷰 표준을 적용하는 실제적인 skill:

````markdown theme={null}
---
name: pr-review-standards
description: Enforce team PR review standards including size limits, test coverage, and documentation requirements
---

## PR Size

- Flag PRs with more than 500 lines changed as "needs splitting"
- Warn on PRs with more than 10 files changed
- Suggest logical split points when flagging oversized PRs
- Auto-generated files (migrations, lockfiles) do not count toward limits

## Test Coverage

- Require test files for any new public function or method
- Flag removed tests without corresponding feature removal
- Check that edge cases are covered, not just happy paths

## Documentation

- Require JSDoc/docstring for exported functions with more than 3 parameters
- Flag breaking API changes without migration guide updates
- Check that README is updated when adding new environment variables

## Review Comment Format

Use this structure for review comments:

```
**[severity]** Brief title

Description of the issue.

**Suggestion:** How to fix it.
```

Severity levels: `critical`, `warning`, `suggestion`, `nitpick`
````

## 문제 해결

<AccordionGroup>
  <Accordion title="Skill 이름이 거부됨">
    `name` 필드는 슬러그 형식이어야 합니다: 소문자, 숫자, 하이픈만 사용. 공백, 언더스코어, 특수문자는 사용할 수 없습니다.

    * `security-checklist` — 유효
    * `Security Checklist` — 유효하지 않음
    * `security_checklist` — 유효하지 않음
  </Accordion>

  <Accordion title="에이전트가 skill 지시를 무시함">
    * skill이 **활성화**되어 있는지 확인하세요 (토글이 켜져 있음)
    * skill이 올바른 기능에 **할당**되어 있는지 확인하세요
    * 지시가 구체적이고 실행 가능한지 확인하세요 — 모호한 가이드는 종종 무시됩니다
    * 짧고 집중된 skill이 길고 광범위한 skill보다 더 안정적으로 적용됩니다
  </Accordion>

  <Accordion title="지시가 너무 길음">
    skill이 수백 줄을 초과하면 여러 개의 집중된 skill로 분리하는 것을 고려하세요. 에이전트는 하나의 방대한 skill보다 여러 개의 짧은 skill을 더 잘 처리합니다.

    도메인별로 분리하세요: 보안 규칙, 성능 가이드라인, 스타일 규칙을 각각의 skill로 분리하세요.
  </Accordion>
</AccordionGroup>

## 관련 문서

<CardGroup cols={2}>
  <Card title="Custom Skills" icon="wand-magic-sparkles" href="/ko/guide/skills/custom-skills">
    워크스페이스에서 skill을 생성, 업로드, 활성화, 할당하세요.
  </Card>

  <Card title="Skills Overview" icon="sparkles" href="/ko/guide/skills/overview">
    Skills가 CloudThinker 플랫폼과 에이전트 워크플로우에 어떻게 맞는지 이해하세요.
  </Card>
</CardGroup>