web-to-markdown

Web to Markdown Converter

This skill takes a webpage URL as input, converts the page content to Markdown format, and saves it.

When to Use

Use this skill for requests such as the following:

"Convert the webpage to Markdown"
"Save this URL as Markdown"
"Make the website content into a Markdown file"
"Archive the webpage"
"Save the blog post as Markdown"
"Convert it so AI can read it well" (AI optimization mode)
"Convert it so it's good to use as context" (AI optimization mode)
"Make both the original and the AI-optimized version" (dual mode) ⭐ NEW

Core Workflow

Step 1: Receive URL input

Receive from the user the URL of the webpage to convert.

Example:

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

Important:

URL은 http:// or https://must start with
HTTP URLs are automatically upgraded to HTTPS
Invalid URLs return an error

Step 2: Select conversion mode

Analyze the user's request and select the appropriate conversion mode.

Conversion modes:

Normal mode (default): Convert the webpage into readable Markdown
AI optimization mode: Convert into a form optimized for AI agents to use as context
Dual mode ⭐ NEW: Create 2 files: original + AI-optimized version

Auto-detection keywords:

"so AI can read it well", "use as context", "for AI training" → AI optimization mode
"original and", "both", "2", "both", "save the original too" → dual mode
Other → normal mode

Example 1 (AI optimization):

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

Example 2 (dual mode):

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

Step 3: Confirm save options

Confirm the save location and filename with the user.

Example:

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

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

Step 4: Fetch and convert the webpage

Use the WebFetch tool to fetch the webpage and convert it to Markdown.

Normal mode prompt

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

AI optimization mode prompt (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 automatically converts HTML to Markdown
A 15-minute cache is applied, so repeated requests for the same URL are fast
If a redirect occurs, request again with the new URL
AI optimization mode reduces tokens by 30-50% and clarifies the structure

Step 5: Save Markdown

Save the converted Markdown as a file.

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

Recommended filenames for AI optimization mode:

Normal: article.md
AI optimization: article-ai-optimized.md or article.context.md

Step 6: Check the result

Shows the saved file path and simple statistics to the user.

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

📄 파일: 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)

Dual Mode Workflow ⭐ NEW

Dual mode generates both the original Markdown and an AI-optimized version. You can secure material for humans to read and material for AI to process at the same time.

Dual Mode Step 1: Check URL and Filename

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

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

Dual Mode Step 2: Generate Original Markdown

Generate the original Markdown using WebFetch with the normal mode prompt.

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

Save original file:

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

Dual Mode Step 3: Generate AI-Optimized Version

CRITICAL: Call WebFetch again for the same URL with the AI-optimized prompt.

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초 안에 파악하고,
사용자의 질문에 정확하게 답변할 수 있도록 최적화
"""

Save AI-optimized file:

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

Dual Mode Step 4: Summarize Results

Show the results of generating the 2 files to the user.

✅ 듀얼 모드 변환 완료! 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 에이전트 컨텍스트로 사용

Dual Mode Filename Rules

Pattern 1: Extension separation (recommended)

Original: article.md
AI-optimized: article.context.md

Pattern 2: Suffix separation

Original: article.md
AI-optimized: article-ai-optimized.md

Pattern 3: Folder separation

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

Advantages of Dual Mode

Preserve original: Material for humans to read is kept as the original
AI efficiency: Token savings and structuring for AI
Separation by purpose: Use files suited to the purpose
Backup effect: Simultaneous backup in 2 forms
Comparable: Comparative analysis of the original and optimized versions is possible

Dual Mode Usage Scenarios

Scenario 1: Technical documentation archiving

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 최적화)

Scenario 2: Blog post backup

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

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

Scenario 3: Building learning materials

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

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

Advanced Options

Batch Conversion of Multiple URLs

You can convert multiple webpages at once.

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로 저장]

Extract Only a Specific Section

You can extract only a specific part of a webpage.

Example:

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

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

Customizing Markdown Format

You can specify the desired Markdown style when converting.

Example:

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

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

Error Handling

Invalid URL

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

Inaccessible page

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

File save error

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

Example Workflows

Example 1: Convert a single webpage

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: Archiving a blog post

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

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

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

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

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

Example 3: View document content only (without saving)

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

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

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

---
# Claude Code

Claude Code is an official CLI...

[전체 내용 출력]
---

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

Technical Details

Using WebFetch

Automatic conversion: Automatic HTML → Markdown conversion
Caching: 15-minute self-cleaning cache
Redirect handling: Automatically re-request to the new URL

Markdown Conversion Quality

WebFetch converts the following elements to Markdown:

Headings (H1-H6)
Paragraphs and text formatting (bold, italic, code)
Links and images
Lists (ordered, unordered)
Code blocks
Blockquotes
Tables

Unnecessary elements are excluded:

Navigation menu
Footer
Ads
Sidebar (depending on the situation)

Saving files

Default path: Current working directory
File extension: .md
Encoding: UTF-8
Overwrite: Overwrite after confirmation if an existing file exists

Best Practices

Use clear filenames: Use filenames that clearly represent the content
Organize folders: When converting multiple pages, organize folders by topic
Check URL: Check that the URL is correct before conversion
Mind copyright: Respect the copyright of webpage content
Personal archiving: Mainly used as personal reference material

Dynamic Content Handling

Problem: JavaScript-rendered pages

WebFetch only fetches static HTML, so pages rendered with JavaScript such as React, Vue, and Next.js may return empty content.

Symptoms:

The converted Markdown is almost empty
Only placeholders such as "Loading..." are visible
Core content is missing

Solution: Playwright fallback

If the content fetched with WebFetch is empty or insufficient, AskUserQuestionis used to ask the user whether to use Playwright.

Step 1: Validate WebFetch results

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

Step 2: Ask the user

Use AskUserQuestion:

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

Step 3-A: Use MCP Playwright (recommended ⭐)

Prerequisites: The MCP Playwright server must be installed.

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

Use in skill:

// 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를 마크다운으로 변환하는 로직

Step 3-B: Use Node Playwright (alternative)

If MCP Playwright is not available, run directly with 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

Save output to a file:

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

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

Step 4: Convert and save

Convert the HTML fetched with Playwright into Markdown.

Option A: Reuse the WebFetch prompt

Put the full HTML fetched with Playwright into the WebFetch prompt to convert it into Markdown.

Option B: Parse directly

Use an HTML → Markdown conversion library (e.g., turndown, html-to-markdown)

Workflow summary

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

MCP Playwright vs Node Playwright comparison

Item	MCP Playwright ⭐	Node Playwright
Installation	MCP server installation required	`npm install playwright`
Invocation method	MCP tool call	Bash command execution
Session management	Automatic	Manual (write script)
Error handling	Clean	Complex
Claude Code integration	Native support	Indirect execution
Recommendation	⭐⭐⭐⭐⭐	⭐⭐⭐

Practical Examples

Scenario: Converting React Official Documentation

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 글자 (전체 콘텐츠 포함)

Additional Option: Auto-detect Mode

For advanced users, --auto-playwright flag can be supported:

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

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

Tips

Long Documents: Very long web pages may include summaries
Dynamic Content: Content rendered with JavaScript can be handled with Playwright ⭐ NEW
Images: Images are included as original URL links (not downloaded)
Re-conversion: If the same URL is requested again within 15 minutes, the cached version is used
MCP Playwright: If there is a lot of dynamic content, installing the MCP Playwright server is recommended

About this skill

When to Use

Core Workflow

Step 1: Receive URL input

Step 2: Select conversion mode

Step 3: Confirm save options

Step 4: Fetch and convert the webpage

Normal mode prompt

AI optimization mode prompt (CRITICAL)

Step 5: Save Markdown

Step 6: Check the result

Dual Mode Workflow ⭐ NEW

Dual Mode Step 1: Check URL and Filename

Dual Mode Step 2: Generate Original Markdown

Dual Mode Step 3: Generate AI-Optimized Version

Dual Mode Step 4: Summarize Results

Dual Mode Filename Rules

Advantages of Dual Mode

Dual Mode Usage Scenarios

Advanced Options

Batch Conversion of Multiple URLs

Extract Only a Specific Section

Customizing Markdown Format

Error Handling

Invalid URL

Inaccessible page

File save error

Example Workflows

Example 1: Convert a single webpage

Example 2: Archiving a blog post

Example 3: View document content only (without saving)

Technical Details

Using WebFetch

Markdown Conversion Quality

Saving files

Best Practices

Dynamic Content Handling

Problem: JavaScript-rendered pages

Solution: Playwright fallback

Step 1: Validate WebFetch results

Step 2: Ask the user

Step 3-A: Use MCP Playwright (recommended ⭐)

Step 3-B: Use Node Playwright (alternative)

Step 4: Convert and save

Workflow summary

MCP Playwright vs Node Playwright comparison

Practical Examples

Additional Option: Auto-detect Mode

Tips