web-to-markdown

web-to-markdown 스킬 개요

web-to-markdown은 로컬에 설치된 web2md CLI를 통해 실제 웹페이지를 깔끔한 Markdown으로 바꾸는, 범위가 명확한 포맷 변환 스킬입니다. 핵심 가치는 “페이지를 요약한다”가 아니라 “실제 브라우저에서 페이지를 렌더링하고, 본문 기사나 문서 영역을 추출한 뒤, 그 결과를 이식성 높은 Markdown으로 변환한다”는 데 있습니다. 그래서 JavaScript 렌더링 페이지, 문서 사이트, 블로그 글, 상호작용 렌더링이 필요한 제한 접근 흐름, 단순 HTTP 요청만으로는 부족한 아카이빙 작업에 특히 잘 맞습니다.

web-to-markdown이 가장 잘 맞는 사용자

이 web-to-markdown 스킬은 다음이 필요한 사용자에게 가장 적합합니다:

• 하나 이상의 URL을 읽기 좋은 Markdown으로 변환하고 싶다
• 클라이언트 측 JavaScript에 의존하는 페이지를 처리해야 한다
• 나중에 분석하거나 재사용할 수 있도록 파일로 저장하고 싶다
• 페이지의 모든 요소를 긁어오기보다 기사형 본문만 추출하고 싶다

실제 목표가 “브라우저에서 이미 열 수 있는 페이지의 핵심 내용만 가져오고 싶다”라면, 이 스킬이 범용 프롬프트보다 더 잘 맞습니다.

web-to-markdown이 다른 점

가장 중요한 차별점은 파이프라인입니다:

• 로컬 Chromium 계열 브라우저를 사용하는 Puppeteer
• 본문 추출용 Readability
• Markdown 변환용 Turndown

이 조합은 원시 HTML이 아니라 렌더링된 콘텐츠를 전제로 설계돼 있습니다. 실무에서는 이 차이 덕분에 일반적인 fetch 기반 도구가 실패하거나 불완전한 결과만 내놓는 페이지에서도 web-to-markdown이 제대로 작동할 수 있습니다.

엄격한 트리거 조건이 중요합니다

이 스킬에는 다소 특이하지만 중요한 제약이 있습니다. 사용자가 use the skill web-to-markdown 같은 식으로 이름을 명시적으로 요청했을 때만 사용해야 합니다. 이런 명시적 트리거가 없으면 스킬을 적용하면 안 됩니다. 디렉터리 사용자 입장에서는 도입 자체는 간단하지만, 호출 규칙을 지키는 것이 중요합니다.

실제로 해결하는 일

대부분의 사용자는 “브라우저 자동화 스킬” 자체를 원하는 것이 아닙니다. 보통 원하는 결과는 다음 중 하나입니다:

• “이 글을 보관할 수 있는 Markdown으로 바꿔줘.”
• “이 문서 페이지는 클라이언트 렌더링이라도 Markdown으로 변환해줘.”
• “여러 URL을 .md 파일들로 일괄 처리해줘.”
• “실제 브라우저로 페이지를 열어서 로그인이나 검증을 통과한 뒤 내용을 저장해줘.”

web-to-markdown은 바로 이런 결과를 내는 데 최적화돼 있습니다.

이런 경우에는 이 스킬을 고르지 마세요

다음에 해당하면 web-to-markdown은 건너뛰는 편이 낫습니다:

• Markdown 출력이 아니라 빠른 요약만 필요하다
• 일반 HTTP fetch만으로도 콘텐츠를 깔끔하게 가져올 수 있다
• 전체 사이트 크롤러나 스크레이퍼가 필요하다
• Playwright 기반 자동화를 원한다. 이 스킬은 다른 브라우저 스택이 아니라 명시적으로 web2md를 사용한다

web-to-markdown 스킬 사용 방법

처음 쓰기 전에 설치 맥락부터 확인하세요

web-to-markdown은 의존성을 두 층으로 봐야 합니다:

1. 에이전트 환경에 설치되는 스킬 자체
2. 동작 가능한 로컬 web2md CLI와 사용 가능한 Chromium 계열 브라우저

실제 설치 경로는 보통 다음과 같습니다:

npx skills add softaworks/agent-toolkit --skill web-to-markdown

저장소 위치:
https://github.com/softaworks/agent-toolkit/tree/main/skills/web-to-markdown

스킬만 추가한다고 끝나지 않습니다. 머신에서 web2md를 실행할 수 없거나 Chrome/Chromium/Brave/Edge를 띄울 수 없으면 제대로 작동하지 않습니다. 이 로컬 브라우저 요구사항이 도입 시 가장 먼저 확인해야 할 핵심 장애물입니다.

먼저 읽어볼 파일

이 스킬은 규모가 작기 때문에 읽는 순서는 아래가 가장 효율적입니다:

1. skills/web-to-markdown/SKILL.md
2. skills/web-to-markdown/README.md

SKILL.md에서는 트리거 규칙, 필수 입력값, 전체 워크플로 형태를 확인할 수 있습니다. README.md에서는 JS 렌더링 페이지, interactive 모드, 일괄 변환처럼 실제 의도된 사용 사례를 검증하면 됩니다.

web-to-markdown에 필요한 입력

안정적으로 web-to-markdown을 사용하려면 다음을 제공하는 것이 좋습니다:

• url 또는 URL 목록
• 출력 방식:
  • stdout으로 출력: --print
  • 파일로 저장: --out ./file.md
  • 디렉터리로 저장: --out ./some-dir/
• 필요 시 브라우저 제어 옵션:
  • 브라우저 자동 감지 실패 시 --chrome-path <path>
  • 로그인 벽, 동의 화면, 사람 확인이 필요한 경우 --interactive

출력 방식을 지정하지 않으면 에이전트가 추측해야 합니다. 이건 굳이 만들 필요 없는 마찰이고, 가장 쉽게 명확히 할 수 있는 부분이기도 합니다.

정확한 호출 조건

이 web-to-markdown 스킬은 사용자가 다음처럼 명시적으로 썼을 때만 트리거되어야 합니다:

• use the skill web-to-markdown ...
• use a skill web-to-markdown ...

테스트할 때도 이름을 직접 써야 합니다. 이것은 선택 가능한 저장소 관례가 아니라, 실행 로직의 핵심입니다.

애매한 요청을 강한 프롬프트로 바꾸기

약한 요청:

• convert this page

강한 요청:

• use the skill web-to-markdown to convert https://example.com/article to Markdown and save it to ./notes/article.md

더 좋은 요청:

• use the skill web-to-markdown to convert these 5 docs URLs to Markdown, save them in ./docs-md/, and use interactive mode if a consent screen appears

좋은 프롬프트는 실패 가능성을 줄여줍니다. 스킬에 다음을 분명히 알려주기 때문입니다:

• 어떤 페이지를 처리할지
• 결과를 어디에 둘지
• 브라우저 상호작용이 필요할 수 있는지
• 단건 작업인지 배치 작업인지

실무에서 요청하기 좋은 명령 패턴

유용한 web-to-markdown 사용 패턴은 다음과 같습니다:

• 단일 페이지를 터미널에 출력: --print
• 단일 페이지를 파일로 저장: --out ./page.md
• 여러 페이지를 폴더에 저장: --out ./pages/
• 까다로운 페이지를 보이는 브라우저로 처리: --interactive
• 브라우저 바이너리 경로를 직접 지정: --chrome-path <path>

저장소에서 안내하는 이런 패턴은 “이 사이트를 스크랩해줘”처럼 스킬 설계 범위를 넘어서는 넓은 요청보다 훨씬 실용적입니다.

단일 페이지 작업에 가장 좋은 워크플로

성공률이 높은 흐름은 보통 이렇습니다:

1. 사용자가 web-to-markdown을 명시적으로 호출했는지 확인한다
2. URL을 받는다
3. 출력할지 저장할지 결정한다
4. 사람의 도움이 필요한 페이지에만 --interactive를 쓴다
5. Markdown 결과에서 누락된 섹션이나 과도한 내비게이션 잡음이 있는지 검토한다
6. 추출이 불완전했다면 브라우저 설정을 조정해 다시 실행한다

처음부터 프롬프트를 과하게 설계하려 하기보다 이 흐름이 더 빠르고 안정적입니다.

여러 URL을 처리할 때 가장 좋은 워크플로

배치 작업이라면:

1. 스킬에 URL 목록을 준다
2. 출력 대상을 디렉터리로 정한다
3. 폴더에 저장할 경우 파일명은 페이지 제목 기준으로 파생될 수 있다고 예상한다
4. 대량 실행 전에 일부 결과를 샘플 점검한다

배치를 쓰는 가장 큰 이유는 일관성입니다. 가장 큰 위험은 사이트 내 모든 페이지 템플릿이 똑같이 잘 추출될 것이라고 가정하는 데 있습니다.

흔한 로컬 설정 장애물

web-to-markdown 설치 실패의 대부분은 프롬프트 문제가 아닙니다. 로컬 환경 문제입니다:

• web2md가 설치되지 않았거나 PATH에 없다
• 로컬에 지원되는 브라우저가 없다
• 브라우저 자동 감지가 실패해 --chrome-path가 필요하다
• 페이지가 보이는 브라우저와 사람의 상호작용을 요구한다

빠르게 도입 가능성을 점검하고 싶다면, 실제 운영 전에 공개 기사 페이지 하나와 JS 비중이 높은 페이지 하나로 먼저 테스트해보는 것이 좋습니다.

출력 품질에서 기대해야 할 것

web-to-markdown의 목표는 원본 페이지를 픽셀 단위로 복제하는 것이 아니라, 깔끔한 본문 중심 Markdown을 만드는 것입니다. 즉:

• 기사와 문서 본문은 대체로 잘 살아난다
• 헤더, 푸터, 광고, 페이지 크롬은 보통 비중이 낮아진다
• 특이한 위젯, 앱 셸, 임베드 도구는 깔끔하게 변환되지 않을 수 있다

이런 트레이드오프는 아카이빙과 분석에는 대체로 바람직하지만, 설치 전에 알고 들어가는 편이 좋습니다.

web-to-markdown 스킬 FAQ

web-to-markdown은 일반 프롬프트보다 더 나은가요?

네, 실제 필요가 렌더링된 페이지 변환이라면 그렇습니다. 범용 프롬프트도 URL에 대해 설명할 수는 있지만, 본질적으로 브라우저를 열고 JavaScript를 기다리고 읽기 좋은 본문을 추출해 Markdown을 만드는 흐름을 수행하진 않습니다. web-to-markdown 스킬의 가치는 바로 이 워크플로를 실제 실행 가능한 형태로 제공한다는 데 있습니다.

web-to-markdown은 초보자에게도 괜찮나요?

네, 작업이 단순하다면 괜찮습니다. URL 하나, 출력 파일 하나, 페이지 구조가 단순한 경우라면 접근하기 쉽습니다. 초보자가 가장 많이 막히는 지점은 스킬 설계가 아니라 로컬 환경 설정입니다. 로컬 브라우저 자동화 CLI를 실행할 수 있다면 충분히 다룰 만합니다.

web-to-markdown은 JavaScript 비중이 높은 페이지도 처리하나요?

바로 그 점이 이 스킬이 존재하는 주요 이유 중 하나입니다. Puppeteer를 통해 실제 로컬 브라우저를 사용하므로, 원시 fetch 방식보다 JS 렌더링 페이지에 훨씬 적합합니다.

web-to-markdown은 로그인이나 검증 화면도 넘어갈 수 있나요?

경우에 따라 가능합니다. --interactive를 쓰면 됩니다. 저장소에는 Chrome을 보여주고 일시 정지한 뒤, 사용자가 직접 필요한 단계를 완료할 수 있는 모드가 명시적으로 지원됩니다. 보호된 페이지나 반쯤 보호된 페이지에서 이것은 꽤 실용적인 장점입니다.

언제 web-to-markdown 스킬을 쓰지 말아야 하나요?

다음 경우에는 사용하지 마세요:

• 사용자가 web-to-markdown을 명시적으로 요청하지 않았다
• 단순 페이지 fetch만으로도 이미 해결된다
• 여러 페이지 구성 요소에 대해 구조화된 스크래핑이 필요하다
• 브라우저를 사용하지 않는 변환 경로를 원한다

이 스킬은 특화되어 있고, 그 특화성은 약점이 아니라 장점입니다.

어떤 브라우저에서든 동작하나요?

문서상으로는 puppeteer-core를 통해 Chrome, Chromium, Brave, Edge 같은 Chromium 계열 브라우저에 맞춰져 있습니다. 자동 감지가 실패하면 경로를 수동으로 넘겨야 할 수 있습니다.

기사 전용인가요?

아니요. 기사가 가장 잘 맞는 유형인 것은 사실이지만, web-to-markdown 스킬은 문서 페이지나 그 밖의 콘텐츠 중심 페이지에서도 “주요 본문 추출”이 적절한 출력 모델이라면 충분히 유용합니다. 반면 대시보드나 고도로 상호작용적인 앱에는 덜 적합합니다.

web-to-markdown 스킬 개선 방법

web-to-markdown에는 출력 지시를 명확히 주세요

더 나은 요청은 단순히 “이 URL 변환해줘”가 아니라 다음처럼 구체적입니다:

• print it
• save it to ./tmp/page.md
• save all results under ./exports/

이렇게 하면 추측 여지가 사라지고, 첫 실행부터 실제 워크플로에 맞는 결과가 나올 가능성이 높아집니다.

페이지에 필요할 때만 interactive 모드를 쓰세요

--interactive는 동의 화면, 로그인 흐름, 검증 프롬프트에 유용하지만 더 느리고 자동화하기 어렵습니다. 일반적인 공개 페이지라면 피하는 편이 좋습니다. 반대로 막힌 페이지라면 무작정 재시도하기보다 초기에 바로 쓰는 편이 낫습니다.

브라우저 감지는 초반에 점검하세요

첫 실행에서 브라우저가 뜨지 않는다면 프롬프트만 계속 바꾸지 마세요. 실행 맥락을 먼저 고쳐야 합니다:

• Chromium 계열 브라우저가 실제로 있는지 확인한다
• 필요하면 --chrome-path <path>를 제공한다

많은 사용자에게 이것이 가장 중요한 web-to-markdown 설치 팁입니다.

대규모 적용 전에 대표 페이지를 먼저 고르세요

수백 개 URL을 변환하기 전에 다음을 시험해보세요:

• 단순한 기사 페이지 1개
• JS 렌더링 페이지 1개
• 동의 또는 로그인 마찰이 있는 페이지 1개

이렇게 해야 이상적인 케이스가 아니라, 실제 사이트 구성 전반에서 이 스킬이 맞는지 판단할 수 있습니다.

페이지별 제약을 프롬프트에 반영하세요

페이지가 까다롭다는 걸 알고 있다면 그대로 말하는 편이 좋습니다:

• use the skill web-to-markdown on this docs page; it renders client-side, save to ./docs/intro.md
• use the skill web-to-markdown on this member page with interactive mode because I need to pass a verification screen first

이런 추가 맥락은 일반적인 수식어를 덧붙이는 것보다 실행 품질에 더 직접적인 영향을 줍니다.

첫 Markdown 결과를 검증한 뒤 조정하세요

첫 출력이 나오면 다음을 확인하세요:

• 핵심 본문이 제대로 담겼는가?
• 내비게이션이나 상투적 보일러플레이트가 너무 많이 들어갔는가?
• 페이지가 일부만 렌더링된 것은 아닌가?
• 파일명이나 폴더 저장 방식이 기대와 맞는가?

그 다음 더 적절한 제어 옵션으로 다시 실행하세요. web-to-markdown은 길고 막연한 프롬프트 실험보다, 한 번의 정확한 재시도로 품질이 좋아지는 경우가 많습니다.

주요 실패 패턴을 알고 계세요

흔한 실패 원인은 다음과 같습니다:

• 명시적 트리거 문구가 없어 스킬이 실행되면 안 되는 경우
• 로컬 브라우저 실행 문제
• 화면에 보이는 상호작용이 필요한 페이지
• Readability가 “주요 본문”을 명확히 판단하기 어려운 페이지
• 사용자가 페이지 변환이 아니라 전체 사이트 스크래핑을 기대하는 경우

이런 패턴을 초기에 알아차리면 web-to-markdown을 계속 써야 할지, 다른 도구로 바꿔야 할지 더 빨리 판단할 수 있습니다.

web-to-markdown은 맞는 출력 기준에 써야 합니다

다음이 성공 기준일 때 가장 좋은 결과를 얻을 수 있습니다:

• 깔끔하고 읽기 좋은 Markdown
• 페이지 크롬보다 본문 중심
• 노트, 아카이브, 분석, 후속 AI 처리에 쓸 수 있는 이식성 높은 출력

성공 기준이 “레이아웃 디테일을 하나도 빠짐없이 보존하는 것”이라면, 이 스킬은 맞는 도구가 아닙니다. 기대치를 설계 의도와 맞추는 것이 결과를 개선하는 가장 빠른 방법입니다.