What is cs-link-sync?

The CS Link Sync skill is a specialized utility designed to maintain the structural integrity of Markdown-based documentation. It automates the detection and repair of broken relative links caused by file renaming, directory restructuring, or typos, ensuring that technical knowledge bases remain navigable and up-to-date with minimal manual effort.

When should I use cs-link-sync?

cs-link-sync is useful in the following scenarios: • Link Synchronization after Refactoring: Automatically update all relative paths and cross-references across multiple directories when documentation files are moved or renamed. • Broken Link Detection and Batch Repair: Scan entire repositories to identify dead links and apply automated fixes based on intelligent file-matching suggestions. • README and Table of Contents Maintenance: Verify that all links in index files, READMEs, and 'Related Documents' sections correctly point to existing files and valid section anchors. • Documentation Integrity Auditing: Perform comprehensive health checks on large-scale technical docs to ensure a seamless user experience and prevent '404 File Not Found' errors within the knowledge base.

name	cs-link-sync
description	CS 문서의 깨진 마크다운 링크를 찾아 수정합니다. "링크 동기화", "깨진 링크 수정", "링크 체크" 요청 시 사용하세요.

CS 링크 동기화 도우미

CS 문서의 폴더 구조나 파일명이 변경될 때 깨진 마크다운 링크를 찾아 수정하는 Skill입니다.

트리거 키워드

"링크 동기화" / "link sync"
"깨진 링크 수정" / "링크 체크"
"링크 검증" / "링크 확인"
"{카테고리} 링크 수정" (예: "network 링크 수정")

링크 패턴

검사 대상 링크 형식

<!-- 상대 경로 링크 -->
[문서명](./파일명.md)
[문서명](../카테고리/파일명.md)

<!-- README 내 링크 -->
- [목차 항목](./path.md)
| [표 내 링크](./path.md) |

<!-- 연관 문서 섹션 -->
| [선수 문서](./path.md) | 선수 지식 | [2] 입문 |

흔한 깨진 링크 패턴

문제 패턴	원인	해결
`./http.md`	파일명 변경됨	`./http-https.md`
`./what-is-db.md`	파일 이동됨	`../what-is-db.md`
`../os/memory.md`	카테고리 변경	`../system-design/memory.md`
`./README.md#section`	섹션명 변경	`./README.md#new-section`

작업 절차

1단계: 전체 스캔

# 모든 CS 문서에서 마크다운 링크 추출
grep -rE '\[.*\]\(\..*\.md\)' cs/

각 링크에 대해:

상대 경로 해석
대상 파일 존재 여부 확인
존재하지 않으면 깨진 링크로 표시

2단계: 깨진 링크 분류

깨진 링크를 원인별로 분류:

분류	설명	자동 수정
파일명 변경	파일 존재하나 이름 다름	가능 (유사 파일 검색)
파일 이동	다른 폴더로 이동됨	가능 (전체 검색)
파일 삭제	파일이 존재하지 않음	불가능 (수동 확인)
오타	단순 타이핑 오류	가능 (유사 파일 검색)

3단계: 자동 수정 후보 제안

깨진 링크마다 수정 후보를 제안:

깨진 링크: ./http.md (cs/network/tcp-ip.md:15)
수정 후보:
  1. ./http-https.md (유사도: 95%)
  2. ../system-design/http-client.md (유사도: 60%)
선택: [1/2/수동 입력]

4단계: 일괄 수정

확인된 수정 사항을 일괄 적용:

# 예시: http.md → http-https.md
find cs/ -name "*.md" -exec sed -i 's|\./http\.md|./http-https.md|g' {} \;

5단계: 결과 보고

## 링크 동기화 결과

### 수정 완료
| 파일 | 라인 | 변경 전 | 변경 후 |
|------|------|--------|--------|
| cs/network/tcp-ip.md | 15 | ./http.md | ./http-https.md |
| cs/os/process.md | 42 | ../what-is-os.md | ./what-is-os.md |

### 수동 확인 필요
| 파일 | 라인 | 깨진 링크 | 사유 |
|------|------|----------|------|
| cs/db/index.md | 23 | ./deleted-file.md | 파일 없음 |

자동화 검사 항목

README 목차 검사

각 카테고리 README.md의 목차 링크가 실제 파일과 일치하는지 확인:

## 전체 목차
- [TCP/IP](./tcp-ip.md)     ← 파일 존재 여부 확인
- [HTTP](./http-https.md)    ← 파일 존재 여부 확인

연관 문서 섹션 검사

각 문서의 ## 연관 문서 섹션 링크 검사:

## 연관 문서
| 문서 | 연관성 | 난이도 |
|------|--------|--------|
| [TCP/IP](./tcp-ip.md) | 선수 지식 | [2] 입문 |  ← 검사

선수 지식 링크 검사

문서 상단의 선수 지식 링크 검사:

> `[3] 중급` · 선수 지식: [TCP/IP](./tcp-ip.md)  ← 검사

사용 예시

전체 링크 검사

사용자: 깨진 링크 확인해줘
Claude:
1. 전체 CS 문서 스캔 (85개)
2. 마크다운 링크 추출 (342개)
3. 깨진 링크 발견 (5개)
4. 수정 제안 및 적용
5. 결과 보고

특정 카테고리만 검사

사용자: network 링크 수정해줘
Claude:
1. cs/network/ 문서만 스캔 (12개)
2. 링크 추출 (48개)
3. 깨진 링크 수정
4. 결과 보고

파일 이동 후 링크 업데이트

사용자: what-is-network.md를 network/로 옮겼어. 링크 동기화해줘
Claude:
1. what-is-network.md 참조하는 모든 파일 검색
2. 경로 업데이트: ../what-is-network.md → ./what-is-network.md
3. 변경된 파일 목록 출력

주의사항

백업 확인: 대량 수정 전 git status 확인
단계별 확인: 자동 수정 전 수정 목록 사용자에게 확인
수동 검토: 파일 삭제로 인한 깨진 링크는 수동 판단 필요
테스트: 수정 후 README 목차 클릭하여 실제 동작 확인

깨진 링크 예방

파일명 변경 시

# 잘못된 방법: 직접 rename
mv http.md http-https.md

# 올바른 방법: 참조 업데이트 포함
# 1. 파일명 변경
# 2. 링크 동기화 스킬 실행
# 3. git add

폴더 구조 변경 시

변경 전 영향받는 링크 목록 확인
폴더 이동
링크 동기화 스킬 실행
README 목차 업데이트

cs-link-sync

When & Why to Use This Skill

Use Cases