notion

Notion の操作

このスキルを使うと、Notion API を通じて Notion のコンテンツ（ページ、データベースのクエリ、検索、ページプロパティの更新）を読み取り、明示的な確認を得たうえで書き込めます。これは Notion プラットフォーム向けのツールスキルです。Notion との連携機能の構築、複雑なブロック構成の作成、Notion API を使ったアプリの開発はアプリケーション開発にあたります。このスキルが対象とするのは、適切なページを探す、データベースから回答する、確認済みの編集を行うといった、日常的なエージェントのワークフローです。

運用上の契約

1. 変更を行う前に、読み取り専用で情報を確認します。 ページの取得、データベースのクエリ、検索は自由に行えます。付属の notion-cli スクリプトは、何も書き込まずに読み取りを行います。
2. 操作の前に、対象、範囲、ロールバック方法を確認します。 ページの作成やプロパティの更新は、チームメイトが参照する共有ワークスペースを変更します。いずれも、人間による明示的な指示に加え、notion-cli による --dry-run プレビューと --yes による確認が必要です。プロパティの更新では既存の値が上書きされるため、確認の前に現在の値と置き換える値を伝えてください。
3. 読み取り範囲を守ります。 Notion は page_size と has_more によってページネーションを行います。タスクに必要な範囲を超えてページを取得しないでください。notion-cli --limit は、すべての検索とクエリの上限を設定します。
4. 根拠の範囲を限定します。 短いページタイトル、プロパティ値、ID を引用してください。ページ全体、トークン、生の API ペイロードをチャットに貼り付けないでください。
5. API バージョンを把握します。 Notion-Version ヘッダーによって API の契約が固定されます。現在動作する読み取り処理も、バージョンの更新によって変わることがあります。notion-cli はデフォルトで 2022-06-28 を送信し、NOTION_VERSION を尊重します。

notion-cli スクリプト

scripts/notion-cli は、Notion API を操作する、エージェント向けに設計された標準ライブラリのみを使用する CLI です。ページ、データベース（クエリ）、検索、更新という、対象となるすべての操作に対応しています。

notion/scripts/notion-cli --help                           # no token or network needed
notion/scripts/notion-cli --json pages get --page-id <page>
# Read only properties you plan to change; absent names are marked explicitly
notion/scripts/notion-cli --json pages get --page-id <page> --property Status --property Reviewer
notion/scripts/notion-cli --json --limit 10 databases query --database-id <db>
notion/scripts/notion-cli --json search query --query "on-call runbook"
notion/scripts/notion-cli pages update --page-id <page> --properties props.json --dry-run
notion/scripts/notion-cli pages update --page-id <page> --properties props.json --yes
notion/scripts/notion-cli pages create --parent-database <db> --title "New row" --yes

終了コード：0 は成功、1 は API エラーまたはチェック失敗、2 は使用方法のエラーです。作成と更新にはガードが設けられており、--dry-run または --yes を指定しない場合、スクリプトは終了コード 1 で拒否し、API を呼び出しません。読み取り範囲は --limit で制限されます（デフォルトは 20、最大は 100 です）。

運用の流れ

1. コンテンツを探す：search query を使ってテキストからページやデータベースを探すか、既知の ID を直接指定します。
2. 範囲を限定して読み取る：単一のページには pages get、データベースの行には databases query を使います（必要に応じて JSON の --filter を指定します）。必ず --limit で上限を設定してください。
3. 回答を整理する：質問と根拠（ページタイトルとプロパティ、データベースの行、has_more の状態を含む検索結果）を対応付けます。
4. 確認を得て操作する：変更は人間からの指示がある場合に限り、--dry-run でプレビューし、--yes で確認したうえで実行します。
5. 検証する：ページを再読み込みし（pages get）、プロパティ値が反映されたことを確認します。

ページ、データベース、検索

• ページ（GET /pages/{id}）：ページには ID、タイトル（title または Name プロパティから抽出）、URL、タイムスタンプ、型付きプロパティの概要が含まれます。JSON 出力には、各プロパティの型、値、完全性が含まれます。--property NAME は繰り返し指定してプロパティを選択できます。指定したプロパティが存在しない場合は、present: false として示されます。人間向けの出力では、不完全なプロパティは <incomplete: reason> と表示されます。長いテキストには省略マーカーと元の文字数も含まれるため、検証済みの完全な値と誤認されることはありません。
• データベース（POST /databases/{id}/query）：page_size の上限を指定して、データベースの行をページとしてクエリできます。必要に応じて、構造化された --filter JSON ファイルも指定できます（例：{"property": "Status", "select": {"equals": "Done"}}）。上限によって後続の行が表示されていない場合は、has_more でわかります。
• 検索（POST /search）：連携機能がアクセス可能なワークスペース全体から、テキストでページやデータベースを検索します。結果は --limit で制限されます。
• 更新（PATCH /pages/{id}）：プロパティの更新では、値（select、status、checkbox、rich text など）が上書きされます。--dry-run でプロパティのペイロードを正確にプレビューし、--yes で確認してください。その後、pages get で再確認します。

統合のアクセスモデル

• Notion の統合はボット形式のトークン（secret_...）で認証し、統合と共有されているページとデータベースのみを参照できます。ワークスペース内に存在していても共有されていないページは、404／object_not_found を返します。これはアクセスモデルによる結果であり、ページが存在しないという意味ではありません。
• Notion-Version ヘッダーで API の契約が選択されます。CLI のデフォルトは 2022-06-28 です。ワークスペースまたはアプリケーションで別のバージョンが指定されている場合は、NOTION_VERSION を設定してください。
• トークンはワークスペースのスコープに限定された認証情報です。環境変数（NOTION_TOKEN）に保存し、コード、チャット、コミットには決して含めないでください。統合トークンが漏えいした場合は、Notion の統合設定で無効にしてください。

リファレンスの参照先

読み込むタイミング	リファレンス
ソース、バージョンに関する注記、更新手順	references/00-source-index.md
API エンドポイント、ページネーション、プロパティの型、フィルター、エラー処理	references/01-api-operations.md

同梱アーティファクト

• scripts/notion-cli：範囲を限定した、標準ライブラリのみを使う CLI（ページの取得／作成／更新、データベースのクエリ、検索。--json、--limit に対応。変更操作は --dry-run／--yes で制御）。
• tests/test_notion_cli.py：スタブ Notion API に対する、決定論的なテスト 21 件。型付きプロパティの読み戻し、明示的な欠落／切り詰め状態、ページネーションの失敗、変更操作のゲート、読み取り専用の契約を含みます。
• references/：日付付きのソースインデックスと API 操作リファレンス。
• evals/evals.json：エージェントの実行を評価する、出力品質に関する 6 件のケース。

検証の範囲

主張	最低限必要な証拠
ページが存在し、そのタイトルがわかる	notion-cli pages get --page-id ... --json がタイトルと ID を返す
データベースのクエリで質問に回答できた	notion-cli databases query --json が has_more の状態とともに、範囲内の行を返す
検索でコンテンツが見つかった	notion-cli search query --json が、一致するページ／データベースを ID とタイトルとともに返す
更新が反映された	notion-cli pages update --yes が終了コード 0 で終了し、続けて実行した pages get --property NAME が、変更した各プロパティの型付きの値を表示する。その値を要求された値と比較する
変更操作を安全に実行できる	notion-cli ... --dry-run が送信予定のペイロードをそのまま表示する

厳守事項

• 人間からの指示、--dry-run によるプレビュー、--yes による確認なしに、ページを作成または更新してはいけません。Notion の編集内容は、そのページにアクセスできる全員に表示されます。
• ページが統合と共有されていないだけの可能性がある場合、ページが存在しないと断言してはいけません。まずアクセスモデルを確認してください。
• --limit を超えてページを読み取ってはいけません。ページ全体、トークン、生のペイロードをチャットに出力してはいけません。
• このスキルは Notion API を操作します。Notion の統合（アプリケーション開発）の構築や、他のナレッジベース製品には対応していません。

使用しない場合

• Notion の統合またはアプリの構築（OAuth フロー、カスタムブロック、公開 API 製品、プロパティ更新を超えるブロックツリーの構成）：これはアプリケーション開発です。サービス設計については backend-engineering を参照してください。
• その他のナレッジベースやドキュメントツール（Confluence、Google Docs、ウィキ）：それぞれに独自のツールがあります。このスキルは Notion のみを対象とします。
• ワークスペースの管理（ユーザー管理、ワークスペース設定、統合の承認）：これらは Notion の管理コンソールで行います。