> ## 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 문서 품질 검증 스킬. 문서 리뷰, 릴리스 전 점검, 깨진 링크·이미지 검사, 중복·고아 파일 탐지, 톤·타겟 독자·셀링 포인트 적합성 점검을 요청받았을 때 사용.

# SKILL

# 문서 품질 검증 스킬

2부 구성: **1부 자동 검사**(명령 실행) → **2부 판단 체크리스트**(사람 수준 판단) → **3부 리포트**.
기존에 알려진 이슈는 [known-issues.md](known-issues.md) 와 대조해 **신규 발생분만** 보고한다.

## 1부. 자동 검사

모든 명령은 저장소 루트에서 실행. 읽기 전용.

> **검사 범위 주의**: `ko/*.mdx` 는 최상위만 매칭해 `ko/dev/`·`ko/ops/` 의 60여 페이지를 조용히 건너뛴다. 아래 명령들은 모두 `ko` 를 재귀로 도는 형태로 통일돼 있으니 축약하지 말 것. `ko/**/*.mdx` 도 zsh 에서만 재귀라 bash 하네스에서는 결과가 달라진다.

### 1. 고아 파일 / 등록 누락

navigation 스킬(`.claude/skills/navigation/SKILL.md`)의 고아 검사 스크립트를 실행한다.
known-issues.md 의 기준선(28개)보다 늘었으면 신규 고아.

### 2. 깨진 내부 링크

**이것이 정본이다.** 앵커(`#...`), `ko/` 밖 경로, 같은 대상의 중복 참조까지 모두 잡는다.

```bash theme={null}
npx mintlify broken-links
```

known-issues.md 에 기록된 기존 **29건(13개 파일)** 과 대조해 **신규분만** 보고한다.

보조 grep — mintlify 를 못 쓸 때만 쓴다. 고유 대상만 보여주므로 **건수가 실제보다 작게 나온다**(앵커·`ko/` 밖 경로 누락, 중복 참조 dedupe):

```bash theme={null}
grep -rhoE '\]\(/ko/[^)#?]+' ko | sed 's/](//' | sort -u \
  | while read p; do [ -f "${p#/}.mdx" ] || echo "대상 없음: $p"; done
```

### 3. 외부 이미지 상태 검사

이미지가 대부분 외부 URL(files.cloudtype.io)이므로 404 검사가 필수:

```bash theme={null}
grep -rhoE 'src="https?://[^"]+"' ko/ | sed 's/src="//;s/"//' | sort -u \
  | while read u; do code=$(curl -sIo /dev/null -w '%{http_code}' "$u"); \
    [ "$code" = "200" ] || echo "$code $u"; done
```

(수십 개 URL 이므로 수 분 걸릴 수 있음. 특정 페이지만 검사하려면 grep 대상을 좁힌다.)

### 4. frontmatter 완결성

```bash theme={null}
find ko -name '*.mdx' | while read f; do
  for k in title description icon; do
    grep -q "^$k:" "$f" || echo "$f: $k 누락"
  done
done
```

`ko/dev/{python,django,flask,fastapi,node,nextjs,nestjs}.mdx` 의 `icon 누락` 7건은 **정당한 예외**다 — 중첩 그룹이 icon 을 가진다(doc-writing 스킬 frontmatter 규칙 참조). 보고에서 제외한다.

### 5. 중복 섹션 후보 (동일 h2 제목)

```bash theme={null}
grep -rh '^## ' ko | sort | uniq -d
```

동일 h2 가 여러 파일에 있으면 내용 중복 의심 — 해당 파일들을 열어 실제 중복인지 확인한다.
단, 모델 연동 페이지들의 "API 키 생성하기"나 배포 예제 페이지들의 "템플릿 선택"처럼 구조가 같아서 나오는 정당한 중복이 대부분이므로 **반드시 본문을 대조**한다. 현재 기준선 29건.

### 6. 스텁 페이지 검출

```bash theme={null}
wc -l $(find ko -name '*.mdx') | sort -n | awk '$1 < 40 && $2 != "total"'
```

40줄 미만이면 스텁 후보. known-issues.md 의 기존 스텁 목록(22개)과 대조.

### 7. 컴포넌트 관례 위반

```bash theme={null}
# 리드 Card 누락 (frontmatter 뒤 첫 요소가 Card 가 아닌 페이지)
find ko -name '*.mdx' | while read f; do
  awk '/^---$/{c++} c==2 && !/^---$/ && NF {print; exit}' "$f" | grep -q '^<Card' \
    || echo "리드 Card 없음: $f"
done

# Frame 없는 img
grep -rln '<img' ko | while read f; do grep -L '<Frame' "$f"; done
```

리드 Card 는 강한 관례이지만 절대 규칙은 아님 — 위반 페이지는 "권고"로 보고.

### 8. 용어집 위반 (대표 패턴)

```bash theme={null}
# 제품 개념을 "스킬"로 표기 (UI 라벨 인용 `설정 > 스킬` 은 정당)
grep -rn '스킬' ko | grep -v '설정 > 스킬' | grep -v '> 스킬'
# 금지 표기
grep -rnE 'knowledge base|글로벌 (모델|데이터)|놀리지베이스' ko
# 워크스페이스 — 외부 서비스 명칭과 개념 설명은 정당하므로 제외 후 확인
grep -rn '워크스페이스' ko \
  | grep -vE '^ko/(slack|notion|jira)\.mdx:' \
  | grep -vE 'Slack|Notion|Jira|슬랙' \
  | grep -v 'Porter AI의 워크스페이스 단위'
```

외부 커넥터 페이지(`ko/{slack,notion,jira}.mdx`)는 페이지 전체가 해당 서비스 맥락이라 줄 단위로는 판별되지 않으므로 경로째 제외한다. 현재 기준선 **0건** — 결과가 나오면 신규 위반이다.

전체 용어집은 doc-writing 스킬 참조.

## 2부. 판단 체크리스트

자동 검사로 잡히지 않는 항목. 페이지를 열어 판단한다:

* [ ] **유형-톤 일치**: 페이지 유형(doc-writing 결정 트리 기준)과 실제 톤이 맞는가? 기능 가이드에 마케팅 문구가, 마케팅형에 구현 세부가 섞여 있지 않은가?
* [ ] **주 독자 1명**: 이 페이지의 주 독자(의사결정자/사용자/개발자/AI 전문가/관리자)가 명확한가? 두 독자를 동시에 겨냥해 초점이 흐려지지 않았나?
* [ ] **핵심 차별점 연결**: AGENTS.md 의 핵심 차별점 5개 중 어느 것을 뒷받침하는지 도입부(Card 리드 또는 첫 문단)에서 드러나는가? 특히 신규 기능 페이지.
* [ ] **여정 정합**: 이 페이지가 전제하는 지식(예: 지식베이스 개념)을 다루는 페이지가 사이드바에서 앞에 있는가?
* [ ] **잠재 고객 관점**: 처음 보는 사람이 이 페이지만 읽어도 "이 기능이 어떤 업무 문제를 푸는지" 알 수 있는가? 기능 명세만 나열돼 있지 않은가?
* [ ] **스크린샷 최신성**: Frame 이미지가 현재 UI 와 다르다는 징후(메뉴명 불일치 등)가 없는가?

## 3부. 리포트 형식

심각도 3단계 표로 보고. **수정은 별도 승인 후에만 진행한다.**

| 심각도 | 기준                                            |
| --- | --------------------------------------------- |
| 차단  | 빌드 실패, 등록됐는데 파일 없음, 깨진 링크/이미지 404             |
| 권고  | 신규 고아 파일, 중복 섹션, frontmatter 누락, 관례 위반, 용어 위반 |
| 참고  | 스텁 후보, 톤 개선 여지, known-issues 에 이미 기록된 항목      |

리포트 마지막에 known-issues.md 갱신 필요 여부를 명시한다 (해소된 이슈 발견 시 목록에서 제거, 신규 이슈는 추가).