​

Porter AI 문서 작성 스킬

​

시작 절차

1. 페이지 유형 판별 (아래 결정 트리)
2. 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)

​

유형별 톤 가이드

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

​

frontmatter 규칙

---
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개가 여기 해당하며 위반이 아니다.

​

컴포넌트 사용 규칙

​

이미지 규칙

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

​

용어집 (고정 표기)

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