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

> Porter AI 문서 페이지(.mdx) 작성·수정 스킬. ko/ 아래 새 페이지를 만들거나 기존 페이지의 본문·frontmatter·컴포넌트를 수정할 때, 페이지 톤·구조·템플릿·용어 표기가 필요할 때 사용.

# SKILL

# Porter AI 문서 작성 스킬

## 시작 절차

1. 페이지 유형 판별 (아래 결정 트리)
2. [templates.md](templates.md) 에서 해당 유형 템플릿을 복사해 시작
3. 작성 — 유형별 톤 가이드와 컴포넌트 규칙 준수
4. 새 페이지라면 **navigation 스킬**로 docs.json 에 등록 (고아 파일 금지)
5. **doc-review 스킬**의 자동 검사로 셀프 체크

## 페이지 유형 결정 트리

* 독자가 "도입할지 말지" 판단하는 단계인가? → **마케팅형** (예: ko/introduction, ko/security, ko/chatgpt-porterai)
* 특정 기능 하나의 사용법인가? → **기능 가이드형** (대부분의 페이지. 예: ko/harness-and-skills, ko/mcp, ko/database)
* 처음부터 끝까지 따라 하는 시나리오인가? → **튜토리얼형** (예: quickstart, 배포 예제)
* 설정값·옵션·항목 비교의 나열인가? → **레퍼런스형** (예: 모델 연동, CLI)

## 유형별 톤 가이드

**공통 규칙: 페이지 도입부에서 AGENTS.md 의 핵심 차별점 5개(보안 / 모델 중립성 / 에이전틱 RAG / 시스템 연결 / 조직 거버넌스) 중 이 페이지가 뒷받침하는 것과 연결한다.**

| 유형      | 톤                               | 구조                                                              |
| ------- | ------------------------------- | --------------------------------------------------------------- |
| 마케팅형    | 문제 제기 → 해결 서사. 비교표·수치 허용, 과장 금지 | 문제(Steps) → 해결 방식(CardGroup) → 다음 단계                            |
| 기능 가이드형 | 개조식, 담백한 설명                     | 정의(Card) → 무엇이 좋은가(Accordion) → 사용 방법(h2 + Frame) → 팁(Tip/Info) |
| 튜토리얼형   | "\~합니다" 진행형 안내                  | 전제 조건 → Steps(각 Step 에 스크린샷 필수) → 결과 확인                         |
| 레퍼런스형   | 표 우선, 서사 최소화                    | 정의(Card) → 표/옵션 목록 → 예외 사항(Note)                                |

* 마케팅 문구를 기능 가이드에 섞지 않는다. 반대로 기능 가이드의 구현 세부를 마케팅형 페이지에 넣지 않는다.
* 문장은 경어체("\~합니다"). 명령형 지시는 "\~합니다"로 서술 (예: "클릭합니다").

## frontmatter 규칙

3필드 필수:

```yaml theme={null}
---
title: '한국어 제목'                       # 사이드바에 그대로 노출
description: '무엇을 안내하는지 한 문장.'   # 경어체, SEO·미리보기 겸용
icon: 'circle-dot'                        # Font Awesome free 아이콘 이름
---
```

* icon 은 새로 고르기 전에 기존 유사 기능 페이지의 아이콘을 재사용할 수 있는지 먼저 확인 (`grep -rh "^icon:" ko | sort | uniq -c`).
* 브랜드·프로토콜 로고가 필요하면 `icon: '/images/icons/{slug}.svg'` 형태로 커스텀 SVG 를 쓴다 → custom-icons 스킬.
* **예외**: 중첩 그룹(앱 배포 플랫폼 탭의 Python·Node.js) 하위 페이지는 그룹이 icon 을 가지므로 페이지 `icon` 을 생략한다. `ko/dev/{python,django,flask,fastapi,node,nextjs,nestjs}.mdx` 7개가 여기 해당하며 위반이 아니다.

## 컴포넌트 사용 규칙

| 컴포넌트                                                                                | 언제 쓰는가                              | 언제 안 쓰는가               |
| ----------------------------------------------------------------------------------- | ----------------------------------- | ---------------------- |
| `<Card>`                                                                            | 페이지 첫 요소, 리드 요약 전용 (제목 없이 본문만도 가능)  | 본문 중간 강조용으로 남용 금지      |
| `<CardGroup cols={2}>` + `<Card href=...>`                                          | 기능 목록을 다른 페이지로 연결할 때                | 링크 없는 단순 나열            |
| `<Frame><img className="block rounded-md" src="..." /></Frame>`                     | 스크린샷 표준형. className 정확히 유지          | Frame 없는 `<img>` 금지    |
| Frame 뒤 `> 인용구`                                                                     | 스크린샷 아래 한 줄 캡션/설명                   | —                      |
| `<Steps>` / `<Step title="...">`                                                    | 순서가 있는 절차만                          | 병렬 나열(목록/CardGroup 사용) |
| `<AccordionGroup>` / `<Accordion defaultOpen={true}>`                               | 부가·심화 설명                            | 2단 중첩까지만, 3단 중첩 금지     |
| `<Tip>`                                                                             | 권장 방법, 알아두면 좋은 것                    | —                      |
| `<Info>`                                                                            | 맥락·조건 (예: "엔터프라이즈에서는 \~")           | —                      |
| `<Note>`                                                                            | 제약·한도 (예: "한 번에 300개까지")            | —                      |
| `<Warning>`                                                                         | 되돌릴 수 없는 동작, 보안 주의                  | —                      |
| HTML `<table>`                                                                      | 비교표 (chatgpt-porterai, database 관례) | 마크다운 표는 쓰지 않음          |
| `<video autoPlay muted loop playsInline className="w-full aspect-video" src="...">` | 짧은 동작 시연                            | —                      |

## 이미지 규칙

* 스크린샷은 `https://files.cloudtype.io/ale-docs/...` 외부 URL 을 사용한다. 업로드는 사람이 하므로, 에이전트는 URL 을 전달받아 삽입만 한다.
* 아직 스크린샷이 없으면 자리에 `{/* TODO: 스크린샷 — 어떤 화면인지 설명 */}` 주석을 남기고 본문을 완성한다.
* 로컬 `images/` 에 새 파일 추가 금지 (로고 등 정적 자산 예외).

## 용어집 (고정 표기)

| 표기                     | 금지 표기                  | 비고                                                                                                                                         |
| ---------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Skills                 | 스킬(제품 개념으로 쓸 때)        | 단, UI 라벨 인용은 화면 그대로: `설정 > 스킬`                                                                                                             |
| MCP 서버                 | MCP서버                  | 띄어쓰기 유지                                                                                                                                    |
| 지식베이스                  | 놀리지베이스, knowledge base |                                                                                                                                            |
| 에이전틱 RAG               | agentic RAG            | 첫 언급 시 "지식베이스(에이전틱 RAG)" 형태 권장                                                                                                             |
| 매니지드 에이전트              | managed agent          |                                                                                                                                            |
| 시크릿                    | secret, 비밀키            |                                                                                                                                            |
| 스페이스                   | space                  | Porter AI 의 스페이스를 "워크스페이스"라고 부르지 않는다. 단 두 경우는 정당 — ①외부 서비스의 자체 명칭(`Slack/Notion/Jira 워크스페이스`) ②`"스페이스는 Porter AI의 워크스페이스 단위입니다"` 형태의 개념 설명 |
| 자체 호스팅 모델              | 셀프호스팅 모델               | 보안 방식으로서의 "Self-Hosting"은 원문 유지 (security.mdx 관례)                                                                                          |
| 전역 모델/전역 데이터/전역 Skills | 글로벌 \~                 |                                                                                                                                            |
| 애플리케이션 배포 플랫폼          | 배포 플랫폼 단독 사용           |                                                                                                                                            |
| AI 운영시스템               | AIOps                  | `ko/ops/aiops.mdx` 의 화면 명칭 (해당 페이지는 현재 비공개)                                                                                                |

* 내부 링크는 절대 경로, 확장자 없이: `[전역 Skills 공유](/ko/ops/global-skills)`.
* **링크 경로는 반드시 docs.json 또는 실제 파일로 확인하고 쓴다.** `157f771` 이후 전역 설정 페이지가 `ko/ops/` 로 옮겨졌고, 옛 경로(`/ko/global-skills`, `/ko/skills`, `/ko/data`, `/ko/vs-chatgpt`, `/ko/dev/openclaw`)를 참조하는 깨진 링크 29건이 아직 남아 있다 — 복사하지 말 것.