Community影像github.com

share-cards

為網站每個頁面建立連結預覽圖片(1200x630 Open Graph 卡片),並在建置時將各頁面的標題、描述、標準網址與圖片標籤寫入 HTML,讓在聊天應用程式與社交網站分享的連結顯示正確預覽,即使是單頁應用程式也能運作。

share-cards 是什麼?

share-cards 是一個專門解決社交分享預覽問題的 AI 代理技能。它針對爬蟲預覽器(如聊天軟體、社交網站、搜尋引擎)不執行 JavaScript 的特性,為單頁應用程式(SPA)的每個頁面生成專屬的 Open Graph 圖片(1200x630 JPEG)與中繼標籤。此技能支援 Claude Code、Cursor 等開發工具,可與 Vite 等建置工具深度整合,在 build 階段自動注入正確的 <title>、description、canonical 及 og:*、twitter:* 標籤。工作流程包含檢查環境、初始化專案設定、定義每個頁面的標題與描述、選擇或自訂模板(editorial、minimal、technical)、渲染卡片、預覽檢核,以及最終的建置整合與驗證。它特別強調文字不可截斷、對比度要足夠,且能產出 Vercel/Netlify 的 rewrite 規則,確保部署後路由正確。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VinVirtual/share-cards/tree/HEAD

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

share-cards 是做什麼的?

爬蟲預覽器(聊天應用程式、社交網站、搜尋引擎)讀取伺服器傳送的 HTML,不會執行 JavaScript。單頁應用程式對每個網址都傳送相同的 HTML,因此每個連結都顯示相同的預覽畫面。share-cards 同時修復這兩個問題:

  1. render:一個 HTML 模板 + 頁面清單 → 每個頁面一張 1200x630 JPEG,在無頭瀏覽器中繪製。
  2. inject:建置後的 index.html → 每個頁面一個 HTML 檔案,各自帶有專屬的 <title>、description、canonical、og:* 與 twitter:* 標籤。

技能資料夾:~/.claude/skills/share-cards/(下文簡寫為 $S)。所有指令格式為 $S/cards <command> [dir],其中 [dir] 內含 cards.config.json。指令 $S/cards help 可列出所有指令。

$S/cards                    指令列工具
$S/lib/                     設定、標籤注入、渲染、驗證、預覽、改寫規則
$S/templates/                editorial.html, minimal.html, technical.html, runtime.js
$S/vite-plugin.mjs          在 `vite build` 後執行 inject
$S/references/templates.md  插槽、變數與自訂模板的方法
$S/examples/site/           一個含 4 個頁面的範例,附有卡片和注入後的頁面
$S/README.md                設定參考、框架注意事項、限制

工作流程

  1. 檢查機器:$S/cards check。只有 render 和 preview 需要瀏覽器。
  2. 找出頁面:閱讀專案的路由器或內容資料夾,列出所有公開網址。找出靜態檔案的提供位置(public/、static/)以及建置輸出位置(dist/、build/、out/)。
  3. 初始化:$S/cards init <project>(當頁面清單應從專案自身的路由或內容資料建構時,加上 --mjs 選項,這樣清單就不會偏離)。設定 siteUrl(真正的 https:// 網域)、siteName、imageDir(位於靜態資料夾內,例如 public/og)、imageUrlPath(該資料夾的對應網址路徑,例如 /og)以及 dist。
  4. 為每個頁面撰寫條目:
    • title:頁面完整標題,應與預覽中顯示的一致。
    • description:一個句子,最多 160 個字元。
    • cardTitle:繪製在卡片上的文字。保持簡短(約 2 至 6 個單詞)。以 *星星* 標記的文字會以強調色繪製。
    • cardDescription(選用,卡片上較短的一行文字)、kicker(小標籤)、art(專案中的圖片檔案)、template(個別頁面覆寫用)。
    • 切勿為這些項目憑空捏造事實、數字或引述。所有文字應直接取自頁面本身。
  5. 挑選模板與主題:editorial(紙張感、粗襯線字體)、minimal(白色、簡潔)、technical(深色、等寬字體)。將 theme 設定為專案本身的色彩。如需其他模板,請執行 $S/cards eject <name> card.html 進行編輯,然後設定 "template": "./card.html"。詳見 references/templates.md。
  6. 渲染:$S/cards render <project>。仔細閱讀每個警告:標題或描述被截斷表示文字必須縮短。
  7. 檢視結果:$S/cards preview <project> 會產生 cards-preview/contact-sheet.png 和 chat-preview.png。務必檢視這兩個 PNG 檔案。檢查每張卡片是否有文字被截斷、過於擁擠、對比度不足,以及圖片遮蓋文字等問題。修正後重新渲染。除非你已親自看過,否則不要告訴使用者卡片看起來沒問題。
  8. 準備頁面外殼:inject 會填入已存在的標籤,若缺少標籤則會失敗。執行 $S/cards tags <project> 並將輸出的區塊貼入原始 index.html 的 <head> 中,取代任何舊的分享標籤(或加上 --add-missing 選項)。
  9. 整合至建置流程:
    • Vite:將 $S/vite-plugin.mjs 中的 shareCards() 加入 plugins 陣列(詳見 README)。
    • 其他工具:在建置指令後執行 $S/cards inject <project>。
  10. 主機規則:若主機有全部轉發至 /index.html 的 catch-all rewrite 規則,請使用 $S/cards rewrites vercel|netlify|netlify-toml <project> 產生頁面規則,並將這些規則放在 catch-all 規則之前。向使用者顯示這些規則;未經告知不得編輯主機設定。
  11. 驗證:建置網站,然後執行 $S/cards verify <project>。必須以 All good. 結尾。
  12. 告知使用者剩餘事項:部署後,將一個真實連結貼到聊天應用程式中。預覽畫面會被各應用程式快取,有時長達數天;設定 "versionImages": true 可在每當卡片變更時改變圖片網址。

規則

  • siteUrl 必須是正式環境的網域。預覽圖片需要絕對路徑的 https:// 網址。
  • 在建置前先渲染卡片,這樣建置時才會複製它們,並將卡片和 cards.lock.json 提交至版本控制。之後 CI 流程便無需瀏覽器。
  • 除非設定檔中設定 "allowNetwork": true,否則渲染時不會從網路取得任何資源。網頁字型必須是列在 fonts 下的本地檔案。
  • 字型預設使用系統字型堆疊,因此在不同機器上繪製的卡片可能不同。若要在所有環境獲得完全一致的輸出,請將字型檔案加入專案(檢查其授權條款)並列在 fonts 下。
  • 坦誠說明未檢查的項目:各應用程式的實際爬蟲行為,以及部署後主機的路由規則。

相關技能