Markdown Anything

<decision_boundary> Use when:

• 使用者要把本地文件轉成 Markdown，例如 PDF、DOCX、PPTX、XLSX、Confluence 匯出。
• 使用者提供一個網址，希望先抓出乾淨 Markdown 再閱讀、存檔或餵給下游流程。
• 任務核心是「先取得可用 Markdown」，而不是直接做研究、摘要、寫作或網站操作。

Do not use when:

• 使用者只要搜尋關鍵字、找官方來源或規劃研究查詢。
• 使用者已經有文件內容，下一步是做證據鏈、摘要、重寫或 spec 整理。
• 使用者要抓 YouTube、下載影音、登入網站操作表單、或進行需要互動的站點流程。
• 來源其實是掃描影像、截圖或低品質 OCR 問題，且目前沒有可靠 OCR 能力。

Inputs:

• 來源本體：本地檔案路徑、URL、或來源清單。
• 完成條件：只預覽、輸出 Markdown、還是要保存為 .md。
• 風險條件：是否可使用第三方代理、是否涉及登入態或敏感資料、是否允許本地寫檔。

Successful output:

• 清楚說明來源判定與轉換路由。
• 產出可用 Markdown，或至少提供保存路徑與可驗證的預覽片段。
• 若失敗，能明確指出卡在權限、工具缺口、隱私限制或來源品質，而不是含糊帶過。 </decision_boundary>

Primary use cases (2-3)

1. 把本地文件轉成可提交的 Markdown

• Trigger examples: "把這份 PDF 轉成 markdown。", "幫我把 Word 整理成 repo 可用的 md。"
• Required inputs: 檔案路徑、是否保留圖片、輸出位置或預設可接受的保存位置。
• Expected result: 根據檔案型態選對工具路徑，輸出 Markdown，並做基本格式清理。

2. 把網址抓成乾淨 Markdown

• Trigger examples: "讀這個網址並輸出 md。", "fetch this link as markdown", "先把這篇文章抓下來再說。"
• Required inputs: URL、是否允許第三方代理、是否只要預覽還是要存檔。
• Expected result: 依站點型態走專用抓取或通用代理級聯，回傳 Markdown 或保存檔路徑。

3. 處理受限平台文件

• Trigger examples: "把這份飛書文件轉成 Markdown。", "這篇微信文章先抓成 md。"
• Required inputs: 平台 URL、可用憑證或登入前提、隱私與代理限制。
• Expected result: 優先走官方 API 或專用抽取；若缺前提，停止並清楚回報需要什麼。

Communication notes

• User vocabulary: 轉 markdown、轉 md、抓網址、匯出 Markdown、把文件整理成 repo 可用格式、保留圖片/表格。
• Avoid jargon: 把 proxy cascade 說成「代理級聯」，把 frontmatter 說成「來源中繼資訊」，把 post-processing 說成「後處理清理」。
• Least-surprise rule: 不要把「已拿到 Markdown」誤包裝成「內容已被正確理解」；本 skill 只保證轉換與清理，不保證分析結論。

Routing boundaries

• Neighboring skills / workflows:
  • web-search-strategy: 需要先找到正確來源，而不是已知來源轉檔時。
  • web-access-advanced: 需要瀏覽器互動、站點操作、動態頁面調查或多網站研究時。
  • longdoc-evidence-reader: 已拿到 Markdown 或長文件後，要做證據鏈與引用時。
  • technical-documentation-writer: 轉完後要重寫成 README、guide、FAQ 或 runbook 時。
• Negative triggers:
  • "幫我查這家公司最新消息。"
  • "讀完這份 PDF 後，整理所有證據與頁碼。"
  • "去網站上幫我登入並完成操作。"
  • "下載這支 YouTube 影片字幕。"
• Handoff rule: 一旦核心問題不再是「如何把來源變成 Markdown」，立刻停在轉換完成點，交給更貼近主任務的 skill。

Language coverage

• Primary language(s): 繁體中文、英文。
• Mixed-language trigger phrases: convert to markdown、docx to md、fetch this URL、read this link、pdf to markdown、飛書轉 md、網址轉 markdown。
• Locale-specific wording risks:
  • 「讀這個網址」有時是要摘要，不一定是要轉檔，先確認成功輸出是否真的要 Markdown。
  • 「整理文件」可能是要重寫，不一定只是轉換，要先分清楚。
  • 「內部文件」通常代表不能隨便送第三方代理，必須先處理隱私邊界。

Host / portability targets

• Primary host(s): Codex、Claude Code、OpenClaw 這類同時具備檔案存取與網路能力的 agent。
• Secondary host(s): 具備 shell / browser / web fetch 能力的 Cursor 類環境。
• Unsupported host(s): 純聊天、無檔案與無網路工具的宿主；無法安全讀本地檔案或 URL 的環境。
• Core portable surface: skill pack only，依賴宿主現有的 shell、web、browser 或 HTTP 工具，不把固定安裝腳本寫死在 skill 內。
• Host adapters / wrappers needed: 可選；若某宿主需要 plugin manifest 或 marketplace 包裝，應保持薄封裝，不可改寫核心流程。
• State / persistence path: 轉換輸出應放在使用者指定路徑、當前工作區或來源檔案旁；不要把暫存、快取、憑證或輸出寫進 skill folder。

<success_criteria> Quantitative:

• Trigger accuracy: 90% 以上的明顯「先轉成 Markdown」需求能命中。
• Tool calls: 一般案例 2-10 次；只有遇到站點專用路由或第二層 fallback 時才增加。
• Failures: 不把第三方代理失敗誤判成來源不存在；不把轉檔完成誤判成內容已驗證正確。

Qualitative:

• 能先判斷來源型態，再選工具，不靠碰運氣亂試。
• 能對私有內容與第三方代理做清楚的 ask-first 邊界。
• 產出格式穩定，可直接銜接下游 skill。 </success_criteria>

Step 1: 盤點可用能力並選主要路由

• Action: 先辨識目前宿主可用的本地轉檔工具、HTTP 讀取能力、瀏覽器能力、官方 API 或代理服務，再依來源型態選主路由。
• Input: 來源類型、宿主能力、敏感度與可用權限。
• Output: 簡短路由表，至少標出主路由與 fallback。
• Validation: 工具選擇應由來源型態與風險驅動，而不是把單一工具當萬用解。

Step 2: 依來源型態執行轉換

• Action:
  • 本地 PDF：優先使用 PDF 轉 Markdown 工具；若可同時抽圖片或做雙工具比較，再決定是否啟用較重路徑。
  • 本地 DOC / DOCX：優先使用對文件結構保留較好的轉換器，再做 Markdown 後處理。
  • 本地 PPTX / XLSX：優先使用能保留表格與段落層級的轉換器。
  • Confluence 匯出：先解決路徑、特殊字元與匯出雜訊，再轉成 Markdown。
  • 一般 URL：優先走公開代理級聯，例如 r.jina.ai -> defuddle.md -> 宿主本地抓取 fallback。
  • WeChat / 微信公眾號：優先走瀏覽器或專用抽取，不要先假設一般代理一定可用。
  • Feishu / Lark 文件或 wiki：優先走官方 API 或專用抓取；沒有憑證時停止並回報。
  • YouTube：直接 handoff，不在本 skill 內處理。
• Input: 來源、主路由、fallback 路由、可用工具。
• Output: 原始 Markdown 或失敗訊號。
• Validation: 有專用通道時不退回一般代理；需憑證或登入態時不得假裝成功。

Step 3: 清理 Markdown 並保留來源中繼資訊

• Action: 針對常見轉換噪音做有限度清理，例如表格崩壞、圖片路徑重複、屬性殘留、CJK 粗體間距、雙重括號連結、縮排破壞 code fence。若可行，補上最小必要的來源中繼資訊，例如標題、來源、原始 URL / 路徑、日期。
• Input: 原始 Markdown、來源型態、清理規則。
• Output: 清理後 Markdown。
• Validation: 只能修正格式與結構噪音，不能杜撰原文沒有的內容；若清理會改變語意，應保留原樣並註記。

Step 4: 做基本品質檢查並決定是否保存

• Action: 檢查標題、段落、表格、圖片參照、程式碼區塊與主要文字是否仍存在；若使用者要求保存，將結果寫成 .md，優先存到指定位置，否則可存到來源檔案旁或工作區合理位置。
• Input: 清理後 Markdown、輸出模式、目的路徑。
• Output: 品質檢查摘要、保存路徑或預覽內容。
• Validation: 若內容過長，不要把整份內容全貼回對話；至少提供保存路徑與可檢閱片段。若要覆寫既有檔案，必須先問。

Step 5: 交棒或停止

• Action: 若下游需求是閱讀、蒐證、寫作或網站操作，明確交給對應 skill；若因隱私、憑證、反爬或工具缺口無法完成，直接列出阻礙與所需前提。
• Input: 轉換結果、未完成事項、下游任務。
• Output: 已完成的 Markdown 交付或具體阻礙說明。
• Validation: 不擴大承接本 skill 邊界外的任務。

Step 6: 最終 QA

• Action: 更新 references/quality_checklist.md 的檢查結果，確保本 skill 的 description、邊界與輸出契約仍與目前流程一致。
• Input: 本輪修改內容、驗證結果、發現的風險。
• Output: readiness 狀態與需要追蹤的缺口。
• Validation: 沒有留下 release-blocking placeholder、失效路徑或未說明的 side effect。 </workflow>

<output_contract> Return exactly these sections in this order:

1. 來源判定
2. 轉換路由
3. Markdown 輸出
4. 品質檢查
5. 阻礙與下一步

Formatting rules:

• 使用 Markdown。
• 來源判定 要用 1-3 句交代來源型態、輸出目標與是否屬於本 skill。
• 轉換路由 要說明主路由、fallback 與任何 ask-first 邊界。
• Markdown 輸出 必須提供以下其一：完整 Markdown、保存路徑加預覽片段、或失敗原因。
• 若內容超長，Markdown 輸出 只顯示精簡片段，並明確標出保存路徑或未保存原因。
• 不可額外自由新增段落。 </output_contract>

<tool_rules>

• 永遠先依來源型態選路由，再選工具；不要先決定工具再找理由。
• 本地文件優先使用本地轉檔工具，不要為了方便先走第三方網路服務。
• 公開一般 URL 可依序考慮 r.jina.ai、defuddle.md 與宿主本地抓取 fallback，但私有或敏感 URL 必須先取得使用者同意才能送第三方代理。
• Feishu / Lark 優先官方 API 或專用抓取；若缺 FEISHU_APP_ID / FEISHU_APP_SECRET 或等價前提，停止並回報。
• WeChat / 微信文章優先專用抽取或瀏覽器能力；一般代理失敗不代表文章不存在。
• YouTube、影音平台與需要帳號互動的頁面不在本 skill 內處理，直接 handoff。
• 在 Windows / WSL 混合環境中，先把路徑正規化，再執行 shell 指令；不要把 Windows 路徑直接餵給只接受 POSIX 路徑的工具。
• 不要自動安裝新工具、寫入系統目錄、要求使用者輸入秘密資訊，除非使用者明確同意。 </tool_rules>

<default_follow_through_policy>

• Directly do: 讀取公開 URL、讀取本地檔案、選路由、做低風險轉換、在使用者指定位置或工作區合理位置保存新的 .md。
• Ask first: 覆寫既有檔案、把私有 URL 送到第三方代理、使用登入中的瀏覽器工作階段、安裝新依賴、寫出工作區外的路徑。
• Stop and report: 缺少來源、缺少必要憑證、內容涉及敏感資料且未允許外送、來源被反爬或登入牆擋住且沒有替代通道、掃描品質過差而目前沒有可靠 OCR。 </default_follow_through_policy>

Output:

來源判定

本地 DOCX 轉 Markdown，屬於本 skill。完成條件是輸出可保存的 .md，並保留圖片參照。

轉換路由

主路由是文件結構優先的 DOCX 轉換器，之後做 Markdown 後處理。若主路由表格保留失敗，再用第二工具做對照。

Markdown 輸出

已保存到 docs/spec.md。

# 規格標題

## 背景
...

品質檢查

標題層級存在，圖片路徑已指向 docs/media/，未發現明顯屬性殘留。

阻礙與下一步

無

Example 2 Input:

• 先把這份飛書文件轉成 Markdown：https://team.feishu.cn/docx/abc123

Output:

來源判定

這是受限平台文件，屬於本 skill，但是否能完成取決於是否有可用 API 或登入前提。

轉換路由

主路由是飛書專用抓取或官方 API。第三方公開代理不是首選，因為可能拿不到受限內容。

Markdown 輸出

尚未輸出。缺少可用的飛書憑證或等價存取能力。

品質檢查

未執行內容檢查，因為來源尚未成功抓取。

阻礙與下一步

請提供可用的飛書存取前提，或改提供已匯出的檔案版本。 </examples>

<model_notes>

• GPT-style models: 要把來源分類、主路由、fallback、ask-first 邊界與輸出格式寫清楚，避免模型直接跳到摘要或分析。
• Reasoning models: 給清楚的 primary job、停止條件與輸出契約即可；不要把具體工具名硬編碼成唯一解，但要保留路由優先序。
• Multi-turn split: 多來源批次任務應拆成「來源盤點 -> 個別轉換 -> 統一 QA -> 交付」四階段，而不是一次吞完。 </model_notes>

Testing plan

Triggering tests

• Should trigger:
  • "把這份 PDF 轉成 markdown，保留圖片。"
  • "讀這個網址並輸出 md，不要先摘要。"
  • "把這個 docx 整理成 repo 可用的 Markdown。"
  • "先把飛書文件抓成 Markdown。"
• Should NOT trigger:
  • "幫我查這間公司今天的最新新聞。"
  • "讀完這份 PDF 後幫我整理證據與頁碼。"
  • "幫我寫一份 README。"
  • "去這個網站上幫我完成登入流程。"
• Near-miss / confusing cases:
  • "讀這個網址" 可能是要摘要，不一定是要 Markdown。
  • "整理這份文件" 可能是重寫，不一定只是轉檔。
  • "內部文件轉 md" 涉及第三方代理時必須先問。
• Should ask before acting:
  • "把這個內網網址抓成 Markdown，直接用你方便的方法。"
  • "把結果直接覆寫原本的 README.md。"

Functional tests

• Test case: DOCX 轉 Markdown
  • Given: 一個含表格、圖片與中英混排粗體的 DOCX。
  • When: 啟動本 skill 進行轉換。
  • Then: 應先走文件結構優先路由，再清理常見 Markdown 噪音，並交付 .md 路徑與品質檢查摘要。
• Test case: 公開網頁轉 Markdown
  • Given: 一個公開文章 URL。
  • When: 啟動本 skill。
  • Then: 應先走通用 URL 路由與級聯 fallback，輸出 Markdown 預覽或保存路徑。
• Test case: 私有飛書文件
  • Given: 一個受限的飛書文件 URL，且沒有可用憑證。
  • When: 啟動本 skill。
  • Then: 應停止並回報缺少的存取前提，而不是假裝成功。

Performance comparison (optional)

• Baseline (no skill): 常直接用單一工具硬轉，容易忽略隱私、專用通道與後處理。
• With skill: 先分類來源，再選路由與 fallback，成功率與可預期性較高。

ROI guardrail

• Quality gain must justify extra:
  • Time: 只接受為了路由判斷與必要清理增加少量時間，不接受無意義多輪重試。
  • Tokens: 回覆應以路由與交付為主，不把整份長文全貼進上下文。
  • Maintenance burden: 核心價值在決策框架，不在綁定單一第三方服務。

Regression gates

• Minimum pass-rate delta: 0.10
• Maximum allowed time increase: 45 秒
• Maximum allowed token increase: 3500
• Maximum under-trigger failures: 1 / 10
• Maximum over-trigger failures: 1 / 10

Feedback loop

• Common failure signals:
  • 明顯轉檔需求卻沒觸發。
  • 對私有 URL 直接走第三方代理。
  • 將 YouTube、搜尋、長文件分析誤收進來。
• Likely fix:
  • description 補強真實 trigger phrases。
  • workflow 補強 ask-first 與 handoff。
  • examples 補強 URL 與本地文件兩條主路徑。

Model / routing checks

• GPT-style prompt pass:
  • 能穩定輸出 5 段固定結構，不偷跑去做摘要。
• Reasoning-model pass:
  • 能在多來源情境下保持來源分類與 ask-first 邊界。
• Neighbor-skill confusion:
  • 需持續檢查是否和 web-access-advanced、longdoc-evidence-reader、technical-documentation-writer 搶 query。

Host compatibility checks

• Primary host smoke tests:
  • Codex：可讀本地檔案、可上網、可保存輸出。
  • Claude Code / OpenClaw：至少有 shell 與 URL 讀取能力時可用。
• Wrapper / manifest / config drift review:
  • 若未來加宿主包裝，不得改寫核心 decision boundary。
• Auth / approval / persistence checks:
  • 私有 URL 外送前必須 ask-first。
  • 輸出不得落到 skill folder。
• Known unsupported hosts:
  • 無網路、無檔案 I/O、無法執行 shell 或無法安全處理登入態的宿主。

Eval workflow

• 把核准過的測試 prompt 保存在 assets/evals/evals.json
• 把 release threshold 保存在 assets/evals/regression_gates.json
• 若要做 with-skill / baseline 比較，先建立固定 workspace 結構，再對照成功率、額外時間與 over-trigger / under-trigger
• 每次 description 或 routing 邊界變更後，都要重跑鄰近 skill 混淆測試

Distribution notes

• Packaging: python skills/skill-creator-advanced/scripts/package_skill.py <path/to/skill-folder>
• 若要為特定宿主提供 wrapper，wrapper 應只補 manifest、安裝敘事與工具映射，不得偷偷分叉核心 workflow
• README、安裝說明與 release notes 應放在 skill folder 外

Troubleshooting

• Symptom: 公開 URL 代理結果為空或只剩殘缺內容

• Cause: 站點需要動態渲染、反爬、登入態或代理服務暫時失效

• Fix: 改走瀏覽器 / 專用抓取 / 本地 fallback，並確認是否其實屬於 web-access-advanced

• Symptom: 本地文件轉出來的表格、圖片或粗體格式很亂

• Cause: 選錯主轉換器，或缺少必要後處理

• Fix: 改用更適合該格式的主路由，並執行有限度格式清理

• Symptom: 私有平台文件抓不到

• Cause: 缺少登入態、API 憑證或必要權限

• Fix: 停止並回報所需前提，不要硬走第三方代理

Resources

• references/quality_checklist.md
• assets/evals/evals.json
• assets/evals/regression_gates.json