Tw Padlet Skill — AI skill for Claude Code

tw-padlet-skill 使用手冊

這是教師使用 Padlet 官方 REST API 的輔助工具，支援讀取看板、種入貼文、建立 Padlet AI recipe 看板，以及在既有貼文留下教師回饋。它不是 Padlet 官方產品，且不會使用瀏覽器自動化、登入、發布、指派或設定分享權限。

能力與限制

可以做	不能做（請在 Padlet 網站手動完成）
讀取看板、貼文、貼文留言	建立指定版面或空白看板、建立欄位
種入單則／批次貼文	設定訪客權限、分享、發布、指派
新增單則／批次純文字教師留言	匯出 PDF、CSV 或 Excel
以 AI recipe 建立新看板	代替教師判斷學生回饋或處理個資

所有會改變 Padlet 的命令都必須在每次執行時附上 `--confirm-write`。沒有旗標，工具會在讀取檔案、金鑰或連線前停止。此旗標代表真實寫入，並非模擬模式。

事前準備

需要 Node.js 18 以上與可使用官方 API 的 Padlet 方案。

cd 
npm install

# 擇一設定，絕不可把真實 key 放進 board.json、comment.json、版本庫、網址或聊天紀錄
export PADLET_API_KEY='...'
# 或：建立權限受限本機設定檔
mkdir -p ~/.tw-edu-skills/padlet
printf '%s' '{"apiKey":"..."}' > ~/.tw-edu-skills/padlet/config.json
chmod 600 ~/.tw-edu-skills/padlet/config.json

node scripts/preflight.mjs

前置檢查只回報金鑰是否存在，不會輸出金鑰。若失敗，請依 JSON 的 `hint` 修正；不要將 key 貼給 agent 或寫入教材資料。

先預覽、再確認、最後寫入

本工具沒有會連到外部服務的 dry-run。請使用下列唯讀命令作為安全預覽，再取得教師確認。任何寫入後，仍應到 Padlet 介面檢視呈現；這是驗證邊界，不能只看程式成功碼。

node scripts/api/get-board.mjs 
node scripts/api/list-posts.mjs 
node scripts/api/list-comments.mjs  

`board-id` 是看板網址結尾的識別碼。先確認看板名稱、目標貼文、學生名單與回饋文字。針對學生的個別建議應先給教師草稿審閱，不應直接發布。

建立貼文與看板

`post.json` 範例：

{
  "subject": "暖身討論",
  "body": "請用一句話描述你對光合作用的理解。",
  "section": "第一組"
}

確認後才執行：

node scripts/api/add-post.mjs  post.json --confirm-write
node scripts/run.mjs board.json --board-id  --confirm-write

# API 唯一的建板路徑：Padlet AI recipe。生成內容須由教師檢查。
node scripts/run.mjs board.json --ai-prompt "國中自然：光合作用討論" --role teacher --confirm-write

輸出中的 `ok:true`、`added` 與 `failed` 必須一起判讀。貼文會比對回傳內容的標題、本文與分欄；若出現 `post-write-verification-failed`，先開啟看板確認，絕不可直接重送。

教師留言

留言僅接收純文字，工具會跳脫 HTML 特殊字元，避免將輸入當作網頁標記。單筆 `comment.json`：

{ "text": "請補上資料來源，並說明你選擇此答案的理由。" }

# 先讀目前留言，確認對象與是否已留言
node scripts/api/list-comments.mjs