Communitygithub.com

Lord1Egypt/awesome-skill-forge

Notion API + ntn CLI:頁面、資料庫、Markdown、Workers。

awesome-skill-forge 是什麼?

此技能為 AI 代理(如 Claude Code、Cursor)提供統一的接口以操作 Notion API,支援兩種互補路徑:`ntn` CLI(macOS/Linux 首選,具備簡潔語法與一站式檔案上傳)和 HTTP + curl(跨平台方案,含 Windows)。核心功能包括讀取/建立/更新頁面與 Markdown 內容、查詢資料庫(資料來源)、上傳檔案,以及進階的 Notion Workers(TypeScript 程式,可排程同步、建立工具和接收 Webhook)。設定上需先建立整合並取得以 `ntn_` 或 `secret_` 開頭的令牌,然後在 `~/.hermes/.env` 中設定 `NOTION_API_KEY`。技能文件提供大量可直接執行的範例指令,涵蓋從基本搜尋到資料庫建立、Worker 生命週期管理的完整操作流程,並說明 2025-09-03 API 版本中資料庫與資料來源的區別,以及 Notion-Flavored Markdown 的進階語法。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/Lord1Egypt/awesome-skill-forge/tree/HEAD/skills/notion

在你喜歡的 AI 中提問

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

說明文件

Notion

以兩種方式與 Notion 對話。兩者使用相同的整合令牌——根據環境選擇適合的方式。

◆ ntn CLI — Notion 官方 CLI。語法更簡潔,可一行指令上傳檔案,Workers 的必要工具。截至 2026 年 5 月僅支援 macOS + Linux(Windows 支援「即將推出」)。已安裝時為預設選項。 ◆ HTTP + curl — 適用於所有平台,包含 Windows。當未安裝 ntn 時的預設備案。

設定

1. 取得整合令牌(兩種路徑皆需)

  1. 在 https://notion.so/my-integrations 建立整合
  2. 複製 API 金鑰(開頭為 ntn_ 或 secret_)
  3. 儲存至 ~/.hermes/.env:
    NOTION_API_KEY=ntn_your_key_here
    
  4. 在 Notion 中與整合分享目標頁面/資料庫:頁面選單 ... → 連線到 → 你的整合名稱。缺少此步驟時,API 即使頁面存在也會回傳 404。

2. 安裝 ntn(macOS / Linux 首選路徑)

# 建議
curl -fsSL https://ntn.dev | bash

# 或透過 npm(需要 Node 22+、npm 10+)
npm install --global ntn

ntn --version    # 驗證

跳過 ntn login — 直接使用整合令牌。 此方式可無瀏覽器執行:

export NOTION_API_TOKEN=$NOTION_API_KEY      # ntn 讀取 NOTION_API_TOKEN
export NOTION_KEYRING=0                       # 不嘗試使用作業系統鑰匙圈

將這些匯出指令加入你的 shell profile(或 ~/.hermes/.env),讓每個工作階段都能繼承它們。

3. 執行階段選擇路徑

if command -v ntn >/dev/null 2>&1; then
  # 使用 ntn
else
  # 備案使用 curl
fi

Windows 使用者:在原生 ntn 釋出之前完全跳過步驟 2——路徑 B 即可正常運作。若想現在就擁有 CLI 的操作體驗,可在 WSL2 內安裝 ntn。

API 基礎知識

所有 HTTP 請求都需要 Notion-Version: 2025-09-03。ntn 會自動處理此標頭。在此版本中,使用者稱為「資料庫」的物件在 API 中稱為資料來源。

路徑 A — ntn CLI(首選,macOS / Linux)

原始 API 呼叫(curl 的簡寫)

ntn api v1/users                                  # GET
ntn api v1/pages parent[page_id]=abc123 \         # POST 內嵌請求主體
  properties[title][0][text][content]="Notes"
ntn api v1/pages/abc123 -X PATCH archived:=true   # PATCH;:= 用於非字串型別(布林/數字/null)

語法說明:

  • key=value — 字串欄位
  • key[nested]=value — 巢狀物件欄位
  • key:=value — 型別指定(布林值、數字、null、陣列)

搜尋

ntn api v1/search query="page title"

讀取頁面中繼資料

ntn api v1/pages/{page_id}

以 Markdown 讀取頁面(代理友善)

ntn api v1/pages/{page_id}/markdown

以區塊讀取頁面內容

ntn api v1/blocks/{page_id}/children

從 Markdown 建立頁面

ntn api v1/pages \
  parent[page_id]=xxx \
  properties[title][0][text][content]="Notes from meeting" \
  markdown="# Agenda\n\n- Q3 roadmap\n- Hiring"

以 Markdown 更新頁面

ntn api v1/pages/{page_id}/markdown -X PATCH \
  markdown="## Update\n\nShipped the prototype."

查詢資料庫(資料來源)

ntn api v1/data_sources/{data_source_id}/query -X POST \
  filter[property]=Status filter[select][equals]=Active

對於包含 sorts、多重篩選條件或複合邏輯的複雜查詢,可透過管道傳入 JSON:

echo '{"filter": {"property": "Status", "select": {"equals": "Active"}}, "sorts": [{"property": "Date", "direction": "descending"}]}' | \
  ntn api v1/data_sources/{data_source_id}/query -X POST --json -

檔案上傳(一行指令——CLI 的最大優勢)

ntn files create < photo.png
ntn files create --external-url https://example.com/photo.png
ntn files list

相比之下,HTTP 流程需要三個步驟(建立上傳 → PUT 位元組 → 引用)。

實用環境變數

變數效果
NOTION_API_TOKEN驗證令牌(覆蓋鑰匙圈)— 設為你的整合令牌
NOTION_KEYRING=0使用 ~/.config/notion/auth.json 的檔案式憑證,而非作業系統鑰匙圈
NOTION_WORKSPACE_ID跳過工作空間選擇提示

路徑 B — HTTP + curl(跨平台,Windows 預設)

所有請求遵循此模式:

curl -s -X GET "https://api.notion.com/v1/..." \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json"

在 Windows 上,Windows 10+ 內建的 curl 即可直接使用。PowerShell 使用者也可以使用 Invoke-RestMethod。

搜尋

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"query": "page title"}'

讀取頁面中繼資料

curl -s "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

以 Markdown 讀取頁面(代理友善)

比區塊 JSON 更容易輸入模型。

curl -s "https://api.notion.com/v1/pages/{page_id}/markdown" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

以區塊讀取頁面內容(當需要結構時)

curl -s "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03"

從 Markdown 建立頁面

POST /v1/pages 接受 markdown 主體參數。

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "xxx"},
    "properties": {"title": [{"text": {"content": "Notes from meeting"}}]},
    "markdown": "# Agenda\n\n- Q3 roadmap\n- Hiring\n\n## Decisions\n- Ship MVP Friday"
  }'

以 Markdown 更新頁面

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}/markdown" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "## Update\n\nShipped the prototype."}'

在資料庫中建立頁面(型別化屬性)

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"database_id": "xxx"},
    "properties": {
      "Name": {"title": [{"text": {"content": "New Item"}}]},
      "Status": {"select": {"name": "Todo"}}
    }
  }'

查詢資料庫(資料來源)

curl -s -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"property": "Status", "select": {"equals": "Active"}},
    "sorts": [{"property": "Date", "direction": "descending"}]
  }'

建立資料庫

curl -s -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "xxx"},
    "title": [{"text": {"content": "My Database"}}],
    "properties": {
      "Name": {"title": {}},
      "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
      "Date": {"date": {}}
    }
  }'

更新頁面屬性

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"Status": {"select": {"name": "Done"}}}}'

附加區塊至頁面

curl -s -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello from Hermes!"}}]}}
    ]
  }'

檔案上傳(三步驟流程)

# 1. 建立上傳
curl -s -X POST "https://api.notion.com/v1/file_uploads" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"filename": "photo.png", "content_type": "image/png"}'

# 2. 將位元組 PUT 至上一步回傳的 upload_url
curl -s -X PUT "{upload_url}" --data-binary @photo.png

# 3. 在頁面/區塊負載中引用 {file_upload_id}

屬性型別

資料庫項目的常見屬性格式:

  • 標題: {"title": [{"text": {"content": "..."}}]}
  • 豐富文字: {"rich_text": [{"text": {"content": "..."}}]}
  • 選擇: {"select": {"name": "Option"}}
  • 多選: {"multi_select": [{"name": "A"}, {"name": "B"}]}
  • 日期: {"date": {"start": "2026-01-15", "end": "2026-01-16"}}
  • 核取方塊: {"checkbox": true}
  • 數字: {"number": 42}
  • 網址: {"url": "https://..."}
  • 電子郵件: {"email": "[email protected]"}
  • 關聯: {"relation": [{"id": "page_id"}]}

API 版本 2025-09-03 — 資料庫 vs 資料來源

  • 資料庫已改稱為資料來源。 查詢和擷取請使用 /data_sources/ 端點。
  • 每個資料庫有兩個 ID: database_id 和 data_source_id。
    • 建立頁面時使用 database_id:parent: {"database_id": "..."}
    • 查詢時使用 data_source_id:POST /v1/data_sources/{id}/query
  • 搜尋時資料庫會以 "object": "data_source" 回傳,並包含 data_source_id 欄位。

Notion Workers(進階,需要 ntn)

Workers 是 Notion 為你代管的 TypeScript 程式。一個 Worker 可以組合暴露以下任何功能:

  • 同步 — 依排程(預設 30 分鐘)從外部 API 拉取資料至 Notion 資料庫。
  • 工具 — 在 Notion 的自訂代理中顯示為可呼叫工具。
  • Webhook — 從外部服務(GitHub、Stripe 等)接收 HTTP 事件並在 Notion 中執行操作。

方案/平台限制:

  • CLI 適用於所有方案。部署 Workers 需要 Business 或 Enterprise 方案。
  • 截至 2026 年 5 月,ntn 僅支援 macOS/Linux。Windows 使用者需要 WSL2 或等候原生支援。
  • 至 2026 年 8 月 11 日免費;之後按 Notion 點數計費。

最小 Worker 範例

ntn workers new my-worker      # 建立 scaffold
cd my-worker
# 編輯 src/index.ts
ntn workers deploy --name my-worker

src/index.ts:

import { Worker } from "@notionhq/workers";

const worker = new Worker();
export default worker;

worker.tool("greet", {
  title: "Greet a User",
  description: "Returns a friendly greeting",
  inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
  execute: async ({ name }) => `Hello, ${name}!`,
});

Webhook 功能

worker.webhook("onGithubPush", {
  title: "GitHub Push Handler",
  execute: async (events, { notion }) => {
    for (const event of events) {
      // event.body, event.rawBody(用於簽章驗證), event.headers
      console.log("got delivery", event.deliveryId);
    }
  },
});

部署後:ntn workers webhooks list 會顯示 Notion 產生的網址。請將此網址視為機密——任何知道它的人都可以 POST 事件,除非你加入簽章驗證。

Worker 生命週期指令

ntn workers deploy
ntn workers list
ntn workers exec <capability-key> -d '{"name": "world"}'
ntn workers sync trigger <key>            # 立即執行同步
ntn workers sync pause <key>
ntn workers env set GITHUB_WEBHOOK_SECRET=...
ntn workers runs list                     # 最近的呼叫
ntn workers runs logs <run-id>
ntn workers webhooks list

當需要建置 Worker 時,使用 ntn workers new 建立 scaffold,在 src/index.ts 中撰寫程式碼,使用 ntn workers env set 設定任何機密,然後部署。Notion 的文件 https://developers.notion.com/workers 涵蓋完整的 API 表面。

Notion 風格 Markdown(由 /markdown 端點使用)

標準 CommonMark 加上用於 Notion 特有區塊的 XML 風格式標籤。使用定位點進行縮排。

超越 CommonMark 的區塊:

<callout icon="🎯" color="blue_bg">
	Ship the MVP by **Friday**.
</callout>

<details color="gray">
<summary>Toggle title</summary>
	子內容縮排一個定位點
</details>

<columns>
	<column>左側</column>
	<column>右側</column>
</columns>

<table_of_contents color="gray"/>

行內:

  • 提及:<mention-user url="..."/>、<mention-page url="...">Title</mention-page>、<mention-date start="2026-05-15"/>
  • 底線:<span underline="true">text</span>
  • 顏色:<span color="blue">text</span> 或區塊級的在第一行使用 {color="blue"}
  • 數學:行內 $x^2$,區塊 $$ ... $$
  • 引用:[^https://example.com]

顏色: gray brown orange yellow green blue purple pink red,加上 *_bg 變體用於背景。

標題 5/6 會摺疊為 H4。多個 > 行會分別轉譯為獨立的引用區塊——若需要多行引用,請在單一 > 內使用 <br>。

選擇正確的路徑

任務macOS / LinuxWindows
讀寫頁面、搜尋、查詢資料庫ntn api ...curl
讀取頁面以供代理總結ntn api v1/pages/{id}/markdowncurl /markdown 端點
上傳檔案ntn files create < file三步驟 HTTP 流程
一次性 API 探索ntn api ...curl
建立由 Notion 代管的同步/Webhook/代理工具ntn workers ...WSL2 + ntn workers ...

注意事項

  • 頁面/資料庫 ID 為 UUID(可含或不含連字號——兩者皆可接受)。
  • 速率限制:約 3 請求/秒平均。CLI 不會繞過此限制。
  • API 無法設定資料庫檢視篩選條件——此為 UI 專屬功能。
  • 建立資料來源時使用 "is_inline": true 可將其嵌入頁面中。
  • 始終對 curl 傳入 -s 以抑制進度條(更乾淨的代理輸出)。
  • 讀取時可透過管道將 JSON 傳入 jq:... | jq '.results[0].properties'。
  • Notion 現在也提供 MCP 伺服器

…

[因翻譯而截斷]

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a insurance agency. Use when handling offer...

Lord1Egypt/awesome-skill-forge

Generates a complete landing page with copy, layout, hero image, and responsive design from a text description. Use when launching a product quickly.

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a family law practice. Use when handling offer...

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a fractional CFO firm. Use when handling offer...

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a home remodeling company. Use when handling offer...

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a HVAC service company. Use when handling offer...

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a immigration law firm. Use when handling offer...

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a CPA tax advisory firm. Use when handling offer...

Lord1Egypt/awesome-skill-forge

Generate a conversion-focused landing page that compares offers, pricing cues, and trust signals for a estate planning law firm. Use when handling...

Lord1Egypt/awesome-skill-forge

Fastest way to create or update a pawr.link profile. One curl command, $19 USDC to create, $0.10 to update. Patch-style update-links endpoint lets you add, remove, or move individual links without replacing the whole profile.

Lord1Egypt/awesome-skill-forge

Use this skill when the user wants to review today, look back on yesterday, reflect on this week, or wrap things up with a gentle, low-pressure reflection.

Lord1Egypt/awesome-skill-forge

Read-only queue dashboard for workspace-aware ship. (gstack)

Lord1Egypt/awesome-skill-forge

Landing page quality assessment for paid advertising campaigns. Evaluates message match, page speed, mobile experience, trust signals, form optimization, and conversion rate potential. Use when user says landing page, post-click experience, landing page audit, LP audit, conversion rate, landing page CRO, post-click CRO, or landing page optimization.

Lord1Egypt/awesome-skill-forge

Create HTML-based video compositions, animated title cards, social overlays, captioned talking-head videos, audio-reactive visuals, and shader transitions using HyperFrames. HTML is the source of truth for video. Use when the user wants a rendered MP4/WebM from an HTML composition, wants to animate text/logos/charts over media, needs captions synced to audio, wants TTS narration, or wants to convert a website into a video.

Lord1Egypt/awesome-skill-forge

Search arXiv papers by keyword, author, category, or ID.

Lord1Egypt/awesome-skill-forge

Delegate coding to OpenAI Codex CLI (features, PRs).

Lord1Egypt/awesome-skill-forge

Track Apple devices/AirTags via FindMy.app on macOS.

Lord1Egypt/awesome-skill-forge

Jailbreak LLMs: Parseltongue, GODMODE, ULTRAPLINIAN.

Lord1Egypt/awesome-skill-forge

Geocode, POIs, routes, timezones via OpenStreetMap/OSRM.

Lord1Egypt/awesome-skill-forge

p5.js sketches: gen art, shaders, interactive, 3D.

相關技能