Markdown.new Skill

Convert public web pages into clean Markdown with markdown.new for AI workflows. Use when tasks require URL-to-Markdown conversion for summarization, RAG ing...

Security Scan

The skill does what it says: it converts public URLs to Markdown by calling markdown.new and contains a small, self-contained Python script; nothing requested or installed is disproportionate to that purpose.

Purpose & Capability

Name/description (URL→Markdown via markdown.new) matches the included script and docs. No unrelated credentials, binaries, or install steps are requested; the payload (POST to https://markdown.new/) is exactly what this skill needs.

Instruction Scope

SKILL.md keeps to the task (validate public http/https URLs, call markdown.new, handle rate limits, write output). It explicitly warns to convert only public pages. Note: instructions emphasize running the script from the skill directory and capturing response headers/metadata; the script can write files when --output/--deliver-md is used, so users should be mindful of output paths.

Install Mechanism

No install spec (instruction-only plus a small script). Nothing is downloaded or extracted by the skill at install time, which reduces risk.

Credentials

The skill requests no environment variables or secrets. However, it sends target URLs to an external service (markdown.new). That is expected for the stated purpose but can leak internal hostnames or private URLs if misused; SKILL.md's guidance to only convert public pages is appropriate and should be followed.

Persistence & Privilege

No 'always: true' or other elevated persistence; user-invocable and agent-autonomy are default and appropriate. The skill does not modify other skills or system-wide config.

Assessment

This skill is internally coherent and simple: it posts the target URL to the markdown.new service and returns Markdown. Before installing or using it, 1) avoid passing private, internal, or paywalled URLs (those URLs will be sent to an external service and could leak information); 2) be careful where you write outputs (the script will create directories and files if you use --output or --deliver-md); 3) the script accepts an --api-url override — only use trusted endpoints (changing this could send URLs to a different, possibly malicious service); and 4) test the skill in a safe environment first (use a public, non-sensitive URL) to confirm behavior. If you need conversion of internal content, consider running a self-hosted conversion tool or verifying the markdown.new service's privacy/terms first.

Markdown.new

Use this skill to convert public URLs into LLM-ready Markdown via markdown.new.

Path Resolution (Critical)

• Resolve relative paths like scripts/... and references/... from the skill directory, not workspace root.
• If current directory is unknown, use an absolute script path.

python3 ~/.codex/skills/markdown-new/scripts/markdown_new_fetch.py 'https://example.com'

cd ~/.codex/skills/markdown-new
python3 scripts/markdown_new_fetch.py 'https://example.com'

Avoid this pattern from an arbitrary workspace root:

python3 scripts/markdown_new_fetch.py 'https://example.com'

Workflow

1. Validate the input URL is public http or https.
2. Run scripts/markdown_new_fetch.py with --method auto first.
3. Re-run with --method browser if output misses JS-rendered content.
4. Enable --retain-images only when image links are required.
5. Capture response metadata (x-markdown-tokens, x-rate-limit-remaining, and JSON metadata when present) for downstream planning.

Quick Start

Commands below assume current directory is the skill root (~/.codex/skills/markdown-new).

python3 scripts/markdown_new_fetch.py 'https://example.com' > page.md

python3 scripts/markdown_new_fetch.py 'https://example.com' --method browser --retain-images --output page.md

python3 scripts/markdown_new_fetch.py 'https://example.com' --deliver-md

Method Selection

• auto: default. Let markdown.new use its fastest successful pipeline.
• ai: force Workers AI HTML-to-Markdown conversion.
• browser: force headless browser rendering for JS-heavy pages.

Use auto first, then retry with browser only when needed.

Delivery Mode

• Use --deliver-md to force file output in .md format.
• In delivery mode, content is wrapped as:
  • <url>
  • ...markdown...
  • </url>
• If --output is omitted, the script auto-generates a filename from the URL.

API Modes

• Prefix mode:
  • https://markdown.new/https://example.com?method=browser&retain_images=true
• POST mode:
  • POST https://markdown.new/
  • JSON body: {"url":"https://example.com","method":"auto","retain_images":false}

Prefer POST mode for automation and explicit parameters.

Limits And Safety

• Treat 429 as rate limiting (documented limit: 500 requests/day/IP).
• Convert only publicly accessible pages.
• Respect robots.txt, terms of service, and copyright constraints.
• Do not treat markdown.new output as guaranteed complete for every page; verify critical extractions.

References

• references/markdown-new-api.md