fix: align all skills with OpenClaw skill references (no --limit on notes, correct field names, note types)

Author: Walle

skills/getnote-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: getnote-auth
-version: 0.2.0
+version: 0.3.0
 description: Manage authentication for Get笔记 CLI
 ---
 
@@ -18,11 +18,11 @@ getnote auth login [--api-key <key>] [--client-id <id>]
 
 | Mode | Command | Description |
 |------|---------|-------------|
-| OAuth (recommended) | `getnote auth login` | Opens browser to authorize |
-| API Key | `getnote auth login --api-key <key>` | Saves key directly, no browser |
+| OAuth (recommended) | `getnote auth login` | Opens browser to authorize; saves credentials automatically |
+| API Key | `getnote auth login --api-key <key>` | Saves key directly, no browser needed |
 
 ```bash
-# OAuth flow
+# OAuth flow (opens browser)
 getnote auth login
 
 # API key directly
@@ -32,7 +32,7 @@ getnote auth login --api-key gk_live_xxx
 getnote auth login --api-key gk_live_xxx --client-id cli_xxx
 ```
 
-API keys start with `gk_live_`. Get yours at: https://www.biji.com/settings/developer
+Get your API key at: https://www.biji.com/settings/developer (keys start with `gk_live_`)
 
 ---
 
@@ -42,6 +42,8 @@ API keys start with `gk_live_`. Get yours at: https://www.biji.com/settings/deve
 getnote auth status
 ```
 
+Shows whether authenticated and which API key is active.
+
 ```bash
 getnote auth status
 ```
@@ -54,7 +56,7 @@ getnote auth status
 getnote auth logout
 ```
 
-Removes saved credentials from local config.
+Removes saved credentials from `~/.getnote/config.json`.
 
 ```bash
 getnote auth logout
@@ -66,5 +68,5 @@ getnote auth logout
 
 - Always run `getnote auth status` first to verify authentication before other commands.
 - If not authenticated, prompt the user to run `getnote auth login`.
-- `--api-key` on any command is a temporary override and does not save credentials.
-- Credentials are stored in `~/.getnote/config.json`; `auth logout` removes them.
+- `--api-key` on any command is a temporary per-invocation override and does not save credentials.
+- Credentials saved at `~/.getnote/config.json`; env vars `GETNOTE_API_KEY` / `GETNOTE_CLIENT_ID` take higher priority.

skills/getnote-kb/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: getnote-kb
-version: 0.2.0
+version: 0.3.0
 description: Manage knowledge bases in Get笔记 via the getnote CLI
 ---
 
 # getnote-kb Skill
 
-Manage knowledge bases in Get笔记 — list, create, browse notes, add/remove notes.
+Manage knowledge bases — list, create, browse notes, add/remove notes.
 
 ## Prerequisites
 
@@ -20,6 +20,8 @@ Manage knowledge bases in Get笔记 — list, create, browse notes, add/remove n
 getnote kbs
 ```
 
+Returns all knowledge bases. Each item includes: `topic_id`, `name`, `description`, `note_count`, `created_at`.
+
 ```bash
 getnote kbs
 getnote kbs -o json
@@ -33,14 +35,15 @@ getnote kbs -o json
 getnote kb <topic_id> [--limit <n>] [--all]
 ```
 
+Returns 20 notes per page by default.
+
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--limit` | 20 | Notes per page |
 | `--all` | — | Fetch all notes (auto-paginate) |
 
 ```bash
 getnote kb vnrOAaGY
-getnote kb vnrOAaGY --limit 5
 getnote kb vnrOAaGY --all
 getnote kb vnrOAaGY -o json
 ```
@@ -55,9 +58,11 @@ getnote kb create <name> [--desc <description>]
 
 ```bash
 getnote kb create "Research Papers"
-getnote kb create "Project Docs" --desc "Documentation links for the main project"
+getnote kb create "Project Docs" --desc "Documentation links"
 ```
 
+> Max 50 knowledge bases per day (resets at 00:00 Beijing time).
+
 ---
 
 ### Add notes to a knowledge base
@@ -66,13 +71,15 @@ getnote kb create "Project Docs" --desc "Documentation links for the main projec
 getnote kb add <topic_id> <note_id> [note_id...]
 ```
 
-Supports multiple note IDs in one call.
+Supports multiple note IDs. Max 20 per call.
 
 ```bash
 getnote kb add vnrOAaGY 1234567890
 getnote kb add vnrOAaGY 1234567890 9876543210
 ```
 
+> Already-existing notes are silently skipped.
+
 ---
 
 ### Remove notes from a knowledge base
@@ -83,14 +90,13 @@ getnote kb remove <topic_id> <note_id> [note_id...]
 
 ```bash
 getnote kb remove vnrOAaGY 1234567890
-getnote kb remove vnrOAaGY 1234567890 9876543210
 ```
 
 ---
 
 ## Agent Usage Notes
 
 - Use `-o json` when parsing results programmatically.
-- Get `topic_id` from `getnote kbs -o json` (the `id` field).
+- Get `topic_id` from `getnote kbs -o json` (the `topic_id` field, not `id`).
 - `kb add` / `kb remove` accept multiple note IDs — prefer batching over multiple calls.
 - Exit code `0` = success; non-zero = error. Error details go to stderr.

skills/getnote-note/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: getnote-note
-version: 0.2.0
+version: 0.3.0
 description: Manage notes in Get笔记 via the getnote CLI
 ---
 
 # getnote-note Skill
 
-Manage individual notes in Get笔记 — save, list, get, update, delete, and track save tasks.
+Save, list, view, update, and delete notes in Get笔记.
 
 ## Prerequisites
 
@@ -25,19 +25,17 @@ getnote save <url|text|image_path> [--title <title>] [--tag <tag>]...
 | `--title` | Optional title |
 | `--tag` | Tag to apply; may be repeated |
 
-- URL (`http://` or `https://`) → saved as link note
-- Local image path → saved as image note
-- Otherwise → saved as text note
+- URL (`http://` or `https://`) → link note (async, auto-polls until done)
+- Local image path → image note (async, auto-polls until done)
+- Otherwise → text note (sync)
 
-**Examples:**
 ```bash
 getnote save https://example.com --title "Great article"
 getnote save "Remember to review the docs" --tag work --tag important
 getnote save ./screenshot.png --title "Design mockup"
 ```
 
-URL saves are async; the CLI auto-polls until done, then shows the result.
-In `-o json` mode, silently polls and returns the final note JSON.
+In `-o json` mode, silently polls and returns the final note JSON (including `title`, `content`/summary, `note_type`, `tags`, `created_at`).
 
 ---
 
@@ -47,35 +45,38 @@ In `-o json` mode, silently polls and returns the final note JSON.
 getnote task <task_id>
 ```
 
-Check progress of an async save task (returned by `save` for URLs).
+Manually check progress of an async save task.
 
 ```bash
-getnote task task_xyz789
 getnote task task_xyz789 -o json
 ```
 
+Returns `status` (`pending` / `processing` / `success` / `failed`) and `note_id` when done.
+
 ---
 
 ### List recent notes
 
 ```
-getnote notes [--limit <n>] [--since-id <id>] [--all]
+getnote notes [--since-id <id>] [--all]
 ```
 
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--limit` | 20 | Notes per page |
-| `--since-id` | — | Pagination cursor (last note ID seen) |
-| `--all` | — | Fetch all notes (auto-paginate, streams output) |
+Returns 20 notes per page (fixed). No `--limit` flag.
+
+| Flag | Description |
+|------|-------------|
+| `--since-id` | Pagination cursor (last note ID seen) |
+| `--all` | Fetch all notes (auto-paginate, streams output) |
 
 ```bash
 getnote notes
-getnote notes --limit 5
 getnote notes --all
 getnote notes --since-id 1234567890
 getnote notes -o json
 ```
 
+**Note types**: `plain_text` / `img_text` / `link` / `audio` / `meeting` / `local_audio` / `internal_record` / `class_audio` / `recorder_audio` / `recorder_flash_audio`
+
 ---
 
 ### Get note details
@@ -84,9 +85,18 @@ getnote notes -o json
 getnote note <id> [--field <field>]
 ```
 
-| Flag | Description |
+Returns full note including content, tags, attachments. Use `--field` to extract a single value.
+
+| `--field` values | Description |
 |------|-------------|
-| `--field` | Output a single field: `id` / `title` / `content` / `type` / `created_at` / `updated_at` / `url` / `excerpt` |
+| `id` | Note ID |
+| `title` | Title |
+| `content` | Content / AI summary |
+| `type` | Note type |
+| `created_at` | Creation time |
+| `updated_at` | Last updated time |
+| `url` | Source URL (link notes) |
+| `excerpt` | Excerpt |
 
 ```bash
 getnote note 1234567890
@@ -107,13 +117,16 @@ getnote note update <id> [--title <title>] [--content <content>] [--tag <tags>]
 |------|-------------|
 | `--title` | New title |
 | `--content` | New content (plain_text notes only) |
-| `--tag` | Comma-separated tags (replaces all existing tags) |
+| `--tag` | Comma-separated tags — **replaces all existing tags** |
 
 ```bash
 getnote note update 1234567890 --title "Updated title"
 getnote note update 1234567890 --tag "work,important"
 ```
 
+> ⚠️ `--tag` replaces all tags. For partial tag changes use `getnote tag add/remove`.
+> ⚠️ Content update only works on `plain_text` notes.
+
 ---
 
 ### Delete a note
@@ -124,12 +137,7 @@ getnote note delete <id> [-y]
 
 Moves note to trash.
 
-| Flag | Description |
-|------|-------------|
-| `-y` | Skip confirmation prompt |
-
 ```bash
-getnote note delete 1234567890
 getnote note delete 1234567890 -y
 ```
 
@@ -138,6 +146,6 @@ getnote note delete 1234567890 -y
 ## Agent Usage Notes
 
 - Use `-o json` when parsing responses programmatically.
-- `save` for URLs is async; in `-o json` mode the CLI auto-polls and returns the final note — no manual `task` polling needed.
-- `note update --tag` replaces **all** existing tags; use `getnote tag add/remove` for partial updates.
+- `notes` list returns **20 per page** (no `--limit`); paginate with `--since-id`.
+- Note IDs are int64 — always handle as strings to avoid precision loss in JavaScript.
 - Exit code `0` = success; non-zero = error. Error details go to stderr.

skills/getnote-search/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: getnote-search
-version: 0.2.0
+version: 0.3.0
 description: Semantic search across notes in Get笔记 via the getnote CLI
 ---
 
@@ -22,9 +22,13 @@ getnote search <query> [--kb <topic_id>] [--limit <n>]
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--kb` | — | Limit search to a knowledge base (topic_id) |
+| `--kb` | — | Limit search to a knowledge base (`topic_id`) |
 | `--limit` | 10 | Max results (max 10) |
 
+Results are ranked by semantic relevance (high → low). Each result includes: `note_id`, `title`, `content` (excerpt), `created_at`, `note_type`.
+
+> Note: `note_id` is only populated for `NOTE` type results. Other types (`FILE`, `BLOGGER`, `LIVE`, etc.) return an empty `note_id`.
+
 ```bash
 # Search across all notes
 getnote search "大模型 API"
@@ -42,6 +46,6 @@ getnote search "机器学习" --limit 5 -o json
 
 - Use `-o json` when parsing results programmatically.
 - Get `topic_id` for `--kb` from `getnote kbs -o json`.
-- Results are ranked by semantic relevance, not recency.
-- Max `--limit` is 10; use `getnote notes` for broader browsing.
+- For `NOTE` type results, use `getnote note <note_id>` to get the full content.
+- Max `--limit` is 10; use `getnote notes` for browsing without a query.
 - Exit code `0` = success; non-zero = error. Error details go to stderr.

skills/getnote-tag/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: getnote-tag
-version: 0.2.0
+version: 0.3.0
 description: Manage note tags in Get笔记 via the getnote CLI
 ---
 
@@ -20,7 +20,12 @@ Add, list, and remove tags on notes.
 getnote tag list <note_id>
 ```
 
-Returns all tags including their IDs (needed for `tag remove`).
+Returns all tags with their IDs and types.
+
+Tag types:
+- `ai` — auto-generated by AI
+- `manual` — added by the user
+- `system` — system tag (**cannot be deleted**)
 
 ```bash
 getnote tag list 1896830231705320746
@@ -47,21 +52,21 @@ getnote tag add 1896830231705320746 工作
 getnote tag remove <note_id> <tag_id>
 ```
 
-> ⚠️ Requires **tag ID** (integer), not tag name. Run `getnote tag list <note_id>` first to get the ID.
-> System tags cannot be removed.
+> ⚠️ Requires **tag ID** (integer from `tag list`), not tag name.
+> ⚠️ `system` type tags cannot be removed.
 
 ```bash
-# Get tag IDs first
+# Step 1: get tag IDs
 getnote tag list 1896830231705320746 -o json
 
-# Remove by tag ID
+# Step 2: remove by tag ID
 getnote tag remove 1896830231705320746 123
 ```
 
 ---
 
 ## Agent Usage Notes
 
-- `tag remove` takes a **tag ID**, not a name — always call `tag list` first if you only have the name.
-- For bulk tag replacement, use `getnote note update --tag` instead (replaces all tags at once).
+- `tag remove` takes a **numeric tag ID**, not a name — always call `tag list` first.
+- To replace all tags at once, use `getnote note update --tag "tag1,tag2"` instead.
 - Exit code `0` = success; non-zero = error. Error details go to stderr.