From be77bf0c9b0635705f7eedeb6a3717b7692f68b2 Mon Sep 17 00:00:00 2001
From: zlei9 <zlei9@126.com>
Date: Sun, 29 Mar 2026 09:38:16 +0800
Subject: [PATCH] Initial commit with translated description

---
 README.md  |  29 ++++++++++++++
 SKILL.md   | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 _meta.json |   6 +++
 3 files changed, 149 insertions(+)
 create mode 100644 README.md
 create mode 100644 SKILL.md
 create mode 100644 _meta.json

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3bc92f0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,29 @@
+# Notion Skill
+
+This skill enables working with Notion pages and databases via the official Notion API.
+
+## Quick Start
+
+1. Create a Notion Integration at https://www.notion.so/my-integrations
+2. Copy the Internal Integration Token
+3. Export it: `export NOTION_API_KEY=secret_xxx`
+4. Share the integration with pages/databases you want to access
+
+## Features
+
+- Read and create pages
+- Append blocks to pages
+- Query databases
+- Create and update database rows
+- Schema inspection and changes (with safety checks)
+
+## Requirements
+
+- `NOTION_API_KEY` environment variable
+- `notion-cli` (Node.js) or `notion-cli-py` (Python) - see installation instructions in SKILL.md
+
+## Version
+
+Current version: 0.1.0
+
+This is a declarative skill that documents safe, recommended operations. The actual API calls are performed by a local CLI tool.
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..1091c0f
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: notion
+description: "通过官方Notion API处理Notion页面和数据库。"
+homepage: https://developers.notion.com
+metadata:
+  clawdbot:
+    emoji: 🧠
+    requires:
+      env:
+        - NOTION_API_KEY
+    install:
+      - id: node
+        kind: note
+        label: "Requires notion-cli (Node.js) or notion-cli-py (Python). See docs below."
+---
+
+# Notion
+
+This skill lets the agent work with **Notion pages and databases** using the official Notion API.
+
+The skill is declarative: it documents **safe, recommended operations** and assumes a local CLI
+(`notion-cli`) that actually performs API calls.
+
+## Authentication
+
+- Create a Notion Integration at https://www.notion.so/my-integrations
+- Copy the Internal Integration Token.
+- Export it as:
+
+```bash
+export NOTION_API_KEY=secret_xxx
+```
+
+Share the integration with the pages or databases you want to access.
+Unshared content is invisible to the API.
+
+## Profiles (personal / work)
+
+You may define multiple profiles (e.g. personal, work) via env or config.
+
+Default profile: personal
+
+Override via:
+
+```bash
+export NOTION_PROFILE=work
+```
+
+## Pages
+
+**Read page:**
+
+```bash
+notion-cli page get <page_id>
+```
+
+**Append blocks:**
+
+```bash
+notion-cli block append <page_id> --markdown "..."
+```
+
+Prefer appending over rewriting content.
+
+**Create page:**
+
+```bash
+notion-cli page create --parent <page_id> --title "..."
+```
+
+## Databases
+
+**Inspect schema:**
+
+```bash
+notion-cli db get <database_id>
+```
+
+**Query database:**
+
+```bash
+notion-cli db query <database_id> --filter <json> --sort <json>
+```
+
+**Create row:**
+
+```bash
+notion-cli page create --database <database_id> --props <json>
+```
+
+**Update row:**
+
+```bash
+notion-cli page update <page_id> --props <json>
+```
+
+## Schema changes (advanced)
+
+Always inspect diffs before applying schema changes.
+
+Never modify database schema without explicit confirmation.
+
+Recommended flow:
+
+```bash
+notion-cli db schema diff <database_id> --desired <json>
+notion-cli db schema apply <database_id> --desired <json>
+```
+
+## Safety notes
+
+- Notion API is rate-limited; batch carefully.
+- Prefer append and updates over destructive operations.
+- IDs are opaque; store them explicitly, do not infer from URLs.
diff --git a/_meta.json b/_meta.json
new file mode 100644
index 0000000..947ba3a
--- /dev/null
+++ b/_meta.json
@@ -0,0 +1,6 @@
+{
+  "ownerId": "kn74xbafpdxdkny48h4mf5dmcd8019j4",
+  "slug": "notion-skill",
+  "version": "1.0.0",
+  "publishedAt": 1769524433792
+}
\ No newline at end of file