web-to-markdown

Web to Markdown Converter

ウェブページのURLを入力すると、そのページの内容をマークダウン形式に変換して保存するスキルです。

When to Use

次のようなリクエストがあった場合に、このスキルを使用してください：

• 「ウェブページをマークダウンに変換して」
• 「このURLをマークダウンで保存して」
• 「ウェブサイトの内容をマークダウンファイルにして」
• 「ウェブページをアーカイブして」
• 「ブログ記事をマークダウンで保存して」
• 「AIが読みやすいように変換して」（AI最適化モード）
• 「コンテキストとして使いやすいように変換して」（AI最適化モード）
• 「元のバージョンとAI最適化バージョンの両方を作って」（デュアルモード）⭐ NEW

Core Workflow

Step 1: URLを入力する

ユーザーに変換したいウェブページのURLを入力してもらいます。

Example:

Claude: 변환하실 웹페이지의 URL을 입력해주세요.
User: https://example.com/article

Important:

• URLはhttp://またはhttps://で始まる必要があります
• HTTP URLは自動的にHTTPSにアップグレードされます
• 無効なURLの場合はエラーが返されます

Step 2: 変換モードを選択する

ユーザーのリクエストを分析し、適切な変換モードを選択します。

変換モード:

1. 通常モード（デフォルト）：ウェブページを読みやすいマークダウンに変換
2. AI最適化モード：AIエージェントがコンテキストとして活用しやすい形式に変換
3. デュアルモード ⭐ NEW：元のバージョンとAI最適化バージョンの2つのファイルを作成

自動検出キーワード:

• 「AIが読みやすいように」、「コンテキストとして使用」、「AI学習用」→ AI最適化モード
• 「元のバージョンと」、「両方」、「2つ」、「both」、「元のバージョンも保存」→ デュアルモード
• その他 → 通常モード

Example 1（AI最適化）:

User: https://example.com/article AI가 읽기 좋게 변환해줘
Claude: AI 최적화 모드로 변환하겠습니다. 구조화된 포맷과 메타데이터를 추가합니다.

Example 2（デュアルモード）:

User: https://example.com/article 원본이랑 AI 최적화 버전 둘 다 만들어줘
Claude: 듀얼 모드로 변환하겠습니다.
- 원본 마크다운 (article.md)
- AI 최적화 버전 (article.context.md)
2개 파일을 생성합니다.

Step 3: 保存オプションを確認する

ユーザーに保存先とファイル名を確認します。

Example:

Claude: 마크다운 파일을 어디에 저장할까요?
옵션:
1. 현재 디렉토리 (./)
2. 특정 경로 지정
3. 파일로 저장하지 않고 내용만 보기

파일명은? (기본값: webpage.md)
User: 현재 디렉토리에 article.md로 저장해줘

Step 4: ウェブページを取得して変換する

WebFetch ツールを使用してウェブページを取得し、マークダウンに変換します。

通常モードのプロンプト

url = "https://example.com/article"
prompt = "웹페이지의 전체 내용을 마크다운 형식으로 변환해주세요. 제목, 본문, 링크, 이미지 등 모든 요소를 포함하되, 불필요한 네비게이션이나 광고는 제외해주세요."

AI最適化モードのプロンプト（CRITICAL）

url = "https://example.com/article"
prompt = """이 웹페이지를 AI 에이전트가 컨텍스트로 활용하기 최적화된 형태로 변환해주세요:

**필수 구조:**

1. **프론트매터 (YAML 형식)**
---
title: "페이지 제목"
url: "원본 URL"
author: "작성자 (있는 경우)"
date: "발행일 (있는 경우)"
word_count: 대략적인 단어 수
topics: ["주제1", "주제2", "주제3"]
summary: |
  이 글의 핵심을 3-5줄로 요약
  AI가 빠르게 파악할 수 있도록
main_points:
  - 핵심 포인트 1
  - 핵심 포인트 2
  - 핵심 포인트 3
content_type: "tutorial|guide|article|documentation|news|blog"
difficulty: "beginner|intermediate|advanced"
---

2. **본문 구조**
# [원본 제목]

## 핵심 요약
[3-5줄로 이 글이 무엇을 다루는지 명확하게]

## 주요 내용
[명확한 계층 구조로 섹션 구분, H2/H3 사용]

### 섹션 1
[내용]

### 섹션 2
[내용]

## 핵심 인사이트
- 인사이트 1
- 인사이트 2
- 인사이트 3

## 실용적 적용
[이 내용을 어떻게 활용할 수 있는지]

## 관련 리소스
[링크가 있다면 설명과 함께]

## 결론
[마무리 요약]

**변환 규칙:**
- 광고, 네비게이션, 푸터, 사이드바 완전 제거
- 코드 블록은 언어 명시 (```python, ```javascript 등)
- 링크는 [설명](URL) 형식으로 명확하게
- 이미지는 ![설명](URL) 형식으로
- 불필요한 수식어 제거, 간결하게
- 리스트는 명확한 bullet points로
- 중요한 개념은 **굵게** 강조

**최종 목표:**
AI가 이 문서를 읽고 핵심을 3초 안에 파악하고,
사용자의 질문에 정확하게 답변할 수 있도록 최적화
"""

Important:

• WebFetchはHTMLを自動的にマークダウンに変換します
• 15分間キャッシュされるため、同じURLへの繰り返しのリクエストも高速です
• リダイレクトが発生した場合は、新しいURLで再度リクエストします
• AI最適化モードでは、トークンを30～50%削減し、構造を明確にします

Step 5: マークダウンを保存する

変換したマークダウンをファイルに保存します。

# Write 도구를 사용하여 파일 저장
Write {
  file_path: "/Users/symverse/workspaces-skill-test/my-skills-hub/article.md"
  content: "[변환된 마크다운 내용]"
}

AI最適化モードの推奨ファイル名:

• 通常：article.md
• AI最適化：article-ai-optimized.mdまたはarticle.context.md

Step 6: 結果を確認する

保存したファイルのパスと簡単な統計情報をユーザーに表示します。

✅ 웹페이지를 마크다운으로 변환했습니다!

📄 파일: article.md
📍 경로: /Users/symverse/workspaces-skill-test/my-skills-hub/article.md
📊 크기: 약 1,234 글자

[View file](computer:///Users/symverse/workspaces-skill-test/my-skills-hub/article.md)

デュアルモードのワークフロー ⭐ NEW

デュアルモードでは、元のマークダウンとAI最適化バージョンの両方を作成します。人が読むための資料とAIが処理するための資料を同時に用意できます。

デュアルモード Step 1: URLとファイル名を確認する

User: https://react.dev/reference/react/useState 원본이랑 AI 최적화 버전 둘 다 만들어줘

Claude: 듀얼 모드로 변환하겠습니다.
기본 파일명은? (기본: webpage)

デュアルモード Step 2: 元のマークダウンを作成する

通常モードのプロンプトを使ってWebFetchで元のマークダウンを作成します。

url = "https://react.dev/reference/react/useState"
prompt = "웹페이지의 전체 내용을 마크다운 형식으로 변환해주세요. 제목, 본문, 링크, 이미지 등 모든 요소를 포함하되, 불필요한 네비게이션이나 광고는 제외해주세요."

元のファイルを保存:

Write {
  file_path: "/path/to/useState.md"
  content: "[원본 마크다운 내용]"
}

デュアルモード Step 3: AI最適化バージョンを作成する

CRITICAL：同じURLに対し、AI最適化プロンプトを使ってWebFetchを再度呼び出します。

url = "https://react.dev/reference/react/useState"  # 동일한 URL
prompt = """이 웹페이지를 AI 에이전트가 컨텍스트로 활용하기 최적화된 형태로 변환해주세요:

**필수 구조:**

1. **프론트매터 (YAML 형식)**
---
title: "페이지 제목"
url: "원본 URL"
author: "작성자 (있는 경우)"
date: "발행일 (있는 경우)"
word_count: 대략적인 단어 수
topics: ["주제1", "주제2", "주제3"]
summary: |
  이 글의 핵심을 3-5줄로 요약
  AI가 빠르게 파악할 수 있도록
main_points:
  - 핵심 포인트 1
  - 핵심 포인트 2
  - 핵심 포인트 3
content_type: "tutorial|guide|article|documentation|news|blog"
difficulty: "beginner|intermediate|advanced"
---

2. **본문 구조**
# [원본 제목]

## 핵심 요약
[3-5줄로 이 글이 무엇을 다루는지 명확하게]

## 주요 내용
[명확한 계층 구조로 섹션 구분, H2/H3 사용]

### 섹션 1
[내용]

### 섹션 2
[내용]

## 핵심 인사이트
- 인사이트 1
- 인사이트 2
- 인사이트 3

## 실용적 적용
[이 내용을 어떻게 활용할 수 있는지]

## 관련 리소스
[링크가 있다면 설명과 함께]

## 결론
[마무리 요약]

**변환 규칙:**
- 광고, 네비게이션, 푸터, 사이드바 완전 제거
- 코드 블록은 언어 명시 (```python, ```javascript 등)
- 링크는 [설명](URL) 형식으로 명확하게
- 이미지는 ![설명](URL) 형식으로
- 불필요한 수식어 제거, 간결하게
- 리스트는 명확한 bullet points로
- 중요한 개념은 **굵게** 강조

**최종 목표:**
AI가 이 문서를 읽고 핵심을 3초 안에 파악하고,
사용자의 질문에 정확하게 답변할 수 있도록 최적화
"""

AI最適化ファイルを保存:

Write {
  file_path: "/path/to/useState.context.md"
  content: "[AI 최적화 마크다운 내용]"
}

デュアルモード Step 4: 結果を要約する

作成した2つのファイルの結果をユーザーに表示します。

✅ 듀얼 모드 변환 완료! 2개 파일이 생성되었습니다.

📄 원본 마크다운:
- 파일: useState.md
- 경로: /path/to/useState.md
- 크기: 약 3,500 글자
- 용도: 사람이 읽기 좋은 원본 보존

[View file](computer:///path/to/useState.md)

📄 AI 최적화 버전:
- 파일: useState.context.md
- 경로: /path/to/useState.context.md
- 크기: 약 2,100 글자 (40% 절감)
- 용도: AI 컨텍스트로 활용

[View file](computer:///path/to/useState.context.md)

💡 팁:
- 원본(.md)은 사람이 읽을 때 사용
- AI 최적화(.context.md)는 RAG 시스템이나 AI 에이전트 컨텍스트로 사용

デュアルモードのファイル名規則

パターン1：拡張子で区別（推奨）

• 元のバージョン：article.md
• AI最適化：article.context.md

パターン2：接尾辞で区別

• 元のバージョン：article.md
• AI最適化：article-ai-optimized.md

パターン3：フォルダーで区別

/docs
├── original/
│   └── article.md
└── optimized/
    └── article.md

デュアルモードのメリット

1. 元のバージョンを保持：人が読むための資料は元の状態のまま維持
2. AIの効率性：AI用はトークンを削減し、構造化
3. 用途別に分離：目的に合ったファイルを使用
4. バックアップ効果：2つの形式で同時にバックアップ
5. 比較可能：元のバージョンと最適化バージョンを比較分析可能

デュアルモードの使用シナリオ

シナリオ1：技術ドキュメントのアーカイブ

User: 이 React 문서들 원본이랑 AI 최적화 버전 둘 다 만들어줘
- https://react.dev/reference/react/useState
- https://react.dev/reference/react/useEffect

Claude: 듀얼 모드로 4개 파일 생성합니다.
- useState.md (원본)
- useState.context.md (AI 최적화)
- useEffect.md (원본)
- useEffect.context.md (AI 최적화)

シナリオ2：ブログ記事のバックアップ

User: 내 블로그 글을 백업하는데 원본도 저장하고 AI가 읽을 수 있는 버전도 만들어줘

Claude: 듀얼 모드로 변환하겠습니다.
- 원본: 사람이 다시 읽을 때
- AI 최적화: 나중에 AI에게 질문할 때

シナリオ3：学習資料の作成

User: 이 튜토리얼들을 둘 다 버전으로 저장해줘

Claude:
study-materials/
├── original/          # 사람이 학습용
│   ├── intro.md
│   └── advanced.md
└── ai-optimized/      # AI 질문 답변용
    ├── intro.context.md
    └── advanced.context.md

Advanced Options

複数のURLを一括変換する

複数のウェブページを一度に変換できます。

Example:

User: 이 URL들을 전부 마크다운으로 저장해줘
- https://example.com/article1
- https://example.com/article2
- https://example.com/article3

Claude: 3개의 웹페이지를 변환하겠습니다. 파일명은 자동으로 생성할까요, 아니면 각각 지정하시겠어요?
User: 자동으로

Claude: [각 URL을 순차적으로 변환하여 article1.md, article2.md, article3.md로 저장]

特定のセクションだけを抽出する

ウェブページの特定の部分だけを抽出できます。

Example:

User: https://example.com/docs 에서 "Installation" 섹션만 마크다운으로 저장해줘

Claude: [WebFetch 프롬프트에 "Installation 섹션만 추출"을 명시하여 해당 부분만 변환]

マークダウンの書式をカスタマイズする

変換時に希望するマークダウンのスタイルを指定できます。

Example:

User: 이 블로그 글을 마크다운으로 변환하되, 모든 제목을 H2(##)로 시작하고 코드 블록은 syntax highlighting 포함해줘

Claude: [WebFetch 프롬프트에 포맷 요구사항을 명시]

Error Handling

URLが無効な場合

User: htp://wrong-url
Claude: ❌ 올바르지 않은 URL입니다. http:// 또는 https://로 시작하는 전체 URL을 입력해주세요.

ページにアクセスできない場合

Claude: ❌ 해당 웹페이지에 접근할 수 없습니다.
- 페이지가 삭제되었거나
- 접근 권한이 필요하거나
- 네트워크 오류가 발생했을 수 있습니다.

ファイルの保存エラー

Claude: ❌ 파일을 저장할 수 없습니다.
- 경로가 올바른지 확인해주세요
- 쓰기 권한이 있는지 확인해주세요
- 디렉토리가 존재하는지 확인해주세요

Example Workflows

Example 1：単一のウェブページを変換する

User: https://docs.python.org/3/tutorial/index.html 이거 마크다운으로 저장해줘

Claude: 파이썬 튜토리얼 페이지를 마크다운으로 변환하겠습니다.
파일명을 어떻게 할까요? (기본: webpage.md)

User: python-tutorial.md

Claude: [WebFetch로 페이지 가져오기]
Claude: [마크다운으로 변환]
Claude: [파일 저장]

✅ 웹페이지를 마크다운으로 변환했습니다!

📄 파일: python-tutorial.md
📍 경로: /Users/symverse/workspaces-skill-test/my-skills-hub/python-tutorial.md
📊 크기: 약 15,234 글자

[View file](computer:///Users/symverse/workspaces-skill-test/my-skills-hub/python-tutorial.md)

Example 2：ブログ記事をアーカイブする

User: 이 블로그 글들을 전부 마크다운으로 저장해서 아카이브 폴더에 넣어줘
- https://blog.example.com/post1
- https://blog.example.com/post2

Claude: 2개의 블로그 글을 archive 폴더에 저장하겠습니다.

[디렉토리 생성]
[각 URL을 순차적으로 변환]

✅ 2개의 웹페이지를 변환했습니다!

📁 archive/
  ├── post1.md
  └── post2.md

Example 3：ドキュメントの内容だけを表示する（保存しない）

User: https://github.com/anthropics/claude-code 이 페이지 내용을 마크다운으로 보여줘만 하고 저장은 하지마

Claude: [WebFetch로 페이지 가져오기]

다음은 해당 페이지의 마크다운 변환 내용입니다:

---
# Claude Code

Claude Code is an official CLI...

[전체 내용 출력]
---

저장하지 않고 내용만 보여드렸습니다.

Technical Details

WebFetchの使用

• 自動変換：HTML → マークダウンに自動変換
• キャッシュ：15分で自動消去されるキャッシュ
• リダイレクト処理：新しいURLに自動で再リクエスト

マークダウン変換の品質

WebFetchは次の要素をマークダウンに変換します：

• 見出し（H1-H6）
• 段落とテキスト書式（bold、italic、code）
• リンクと画像
• リスト（ordered、unordered）
• コードブロック
• 引用
• テーブル

不要な要素は除外されます：

• ナビゲーションメニュー
• フッター
• 広告
• サイドバー（状況による）

ファイルの保存

• デフォルトのパス：現在の作業ディレクトリ
• ファイル拡張子：.md
• エンコーディング：UTF-8
• 上書き：既存のファイルがある場合は確認後に上書き

Best Practices

1. 分かりやすいファイル名を使用する：内容がよく分かるファイル名を使用
2. フォルダー構成を整理する：複数のページを変換する場合は、テーマごとにフォルダーを整理
3. URLを確認する：変換前にURLが正しいことを確認
4. 著作権に注意する：ウェブページの内容の著作権を尊重
5. 個人用にアーカイブする：主に個人的な参考資料として使用

Dynamic Content Handling（動的コンテンツの処理）

問題：JavaScriptでレンダリングされるページ

WebFetchは静的HTMLのみを取得するため、React、Vue、Next.jsなどを使ってJavaScriptでレンダリングされるページでは、内容が空のまま返される場合があります。

症状:

• 変換されたマークダウンがほぼ空
• 「Loading...」のようなプレースホルダーだけが表示される
• 主要なコンテンツが欠落している

解決策：Playwrightへのフォールバック

WebFetchで取得した内容が空、または不十分な場合は、AskUserQuestionを使用してPlaywrightを使用するかどうかをユーザーに尋ねます。

Step 1: WebFetchの結果を検証する

# WebFetch로 가져온 마크다운 내용 확인
if len(markdown_content.strip()) < 500:  # 너무 짧으면
    # 동적 콘텐츠일 가능성 높음

ステップ 2：ユーザーに尋ねる

AskUserQuestion を使用：

AskUserQuestion {
  questions: [
    {
      question: "이 페이지는 동적 콘텐츠(JavaScript)를 사용하는 것 같습니다. Playwright를 실행해서 브라우저로 데이터를 가져올까요?",
      header: "Playwright",
      multiSelect: false,
      options: [
        {
          label: "Yes, Playwright로 재시도",
          description: "Chromium 브라우저를 실행해서 JavaScript 렌더링 후 콘텐츠 가져오기 (느림, 정확함)"
        },
        {
          label: "No, 현재 내용만 저장",
          description: "WebFetch 결과만 저장 (빠름, 불완전할 수 있음)"
        }
      ]
    }
  ]
}

ステップ 3-A：MCP Playwright を使用（推奨 ⭐）

**事前準備：**MCP Playwright サーバーがインストールされている必要があります。

# 최초 1회만 설치
npx @modelcontextprotocol/server-playwright

スキルで使用：

// 1. 페이지 이동
mcp__playwright__navigate({
  url: "https://example.com"
})

// 2. JavaScript 렌더링 대기
mcp__playwright__waitForLoadState({
  state: "networkidle"
})

// 3. HTML 콘텐츠 가져오기
const htmlContent = mcp__playwright__getContent()

// 4. 마크다운으로 변환 (WebFetch 프롬프트 재사용)
// htmlContent를 마크다운으로 변환하는 로직

ステップ 3-B：Node Playwright を使用（代替）

MCP Playwright がない場合は、Node.js で直接実行します：

# Playwright 스크립트 실행
node << 'EOF'
const playwright = require('playwright');

(async () => {
  const browser = await playwright.chromium.launch({ headless: true });
  const page = await browser.newPage();

  console.log('⏳ 페이지 로딩 중...');
  await page.goto('https://example.com', { waitUntil: 'networkidle' });

  console.log('⏳ JavaScript 렌더링 대기 중...');
  await page.waitForTimeout(3000); // 3초 대기

  const content = await page.content();
  console.log(content);

  await browser.close();
})();
EOF

出力をファイルに保存：

# HTML을 임시 파일로 저장
node playwright-script.js > temp.html

# 이제 이 HTML을 마크다운으로 변환
# (WebFetch 대신 직접 변환 로직 사용)

ステップ 4：変換して保存

Playwright で取得した HTML を Markdown に変換します。

オプション A：WebFetch プロンプトを再利用

Playwright で取得した HTML 全体を WebFetch プロンプトに入力し、Markdown に変換します。

オプション B：直接パース

HTML → Markdown 変換ライブラリを使用します（例：turndown、html-to-markdown）。

ワークフローの概要

1. WebFetch로 시도 (빠름)
   ↓
2. 결과 검증 (내용이 충분한가?)
   ↓ NO
3. AskUserQuestion (Playwright 사용할까요?)
   ↓ YES
4. Playwright로 재시도
   ├─ MCP Playwright (권장) 또는
   └─ Node Playwright (대안)
   ↓
5. 마크다운 변환 및 저장

MCP Playwright と Node Playwright の比較

項目	MCP Playwright ⭐	Node Playwright
インストール	MCP サーバーのインストールが必要	npm install playwright
呼び出し方法	MCP ツールを呼び出す	Bash コマンドを実行
セッション管理	自動	手動（スクリプトを作成）
エラーハンドリング	シンプル	複雑
Claude Code との統合	ネイティブ対応	間接的に実行
おすすめ度	⭐⭐⭐⭐⭐	⭐⭐⭐

実践例

シナリオ：React 公式ドキュメントの変換

User: https://react.dev/reference/react/useState 마크다운으로 변환해줘

Claude: [WebFetch 시도]
Claude: ⚠️ 이 페이지는 JavaScript로 렌더링되는 것 같습니다.
        내용이 거의 비어있네요.

[AskUserQuestion 호출]

User: Yes, Playwright로 재시도

Claude: ⏳ Playwright로 페이지 로딩 중...
Claude: ✅ JavaScript 렌더링 완료
Claude: ✅ 마크다운 변환 완료

📄 파일: useState.md
📍 경로: /path/to/useState.md
📊 크기: 약 5,234 글자 (전체 콘텐츠 포함)

追加オプション：自動検出モード

上級ユーザー向けに、--auto-playwright フラグをサポートできます：

User: https://react.dev/reference/react/useState 마크다운으로 변환해줘 (자동으로 Playwright 사용해도 돼)

Claude: [WebFetch 시도]
Claude: [자동으로 Playwright 폴백]
Claude: ✅ 마크다운 변환 완료

ヒント

• 長いドキュメント：非常に長いウェブページは要約される場合があります
• 動的コンテンツ：JavaScript でレンダリングされるコンテンツは Playwright で対応できます ⭐ NEW
• 画像：画像は元の URL リンクとして含まれます（ダウンロードされません）
• 再変換：同じ URL を 15 分以内に再度リクエストすると、キャッシュされたバージョンが使用されます
• MCP Playwright：動的コンテンツが多い場合は、MCP Playwright サーバーのインストールをおすすめします