diy-pc-ingest
Setup (required)
This skill is intended to be shared. Do not hardcode your Notion IDs or token in the skill.
Resolve and read the installed Notion dependency before execution:
- Its model-facing skill name is
notion; its ClawHub package slug is
notion-api-automation. Read it with skills_read(name="notion").
If unavailable, use skills_search to locate an eligible Notion CLI skill and
read its complete instructions. A slug or directory name is not a skill name.
- Use the returned
SKILL.md location to resolve scripts/notionctl.mjs on the
same execution host as this skill. Do not assume both skills share a parent
directory: workspace, grouped, managed, extra and revision paths can differ.
- Pass that absolute CLI path with
--notionctl-path (preferred) or set the
non-secret NOTIONCTL_PATH environment variable. Explicit paths take priority
over the legacy sibling/scoped-root fallback; invalid explicit paths fail
without searching another route.
- Check
node <resolved-notionctl-path> --help for api, --compact,
--method, --path and --body-json. The API bridge must return
{ok:true,result:...}. Discovery/metadata does not guarantee this capability.
Do not reinstall a working dependency just because this skill was updated.
Only if the dependency is missing, use OpenClaw's install path for the intended
agent (replace <agent-id> with the configured agent, not a human profile ID):
openclaw skills install @tristanmanchester/notion-api-automation --agent <agent-id>
OpenClaw does not enforce cross-skill dependencies or optional environment
variables through dependsOnSkills, optionalEnv or network metadata fields.
The checks above and the data-flow rules below are part of this skill's procedure.
- Read the
DIY-PC Notion Targets table in the workspace AGENTS.md ## Tools section for the data_source_id and database_id values for each target. Pass them as explicit CLI arguments:
--pcconfig-dsid, --pcconfig-dbid
--pcinput-dsid, --pcinput-dbid
--storage-dsid, --storage-dbid
--enclosure-dsid, --enclosure-dbid
- Provide Notion auth for
notion-api-automation (notionctl):
- env:
NOTION_API_KEY (legacy shell/service env remains supported)
- OpenClaw config:
skills.entries["diy-pc-ingest"].apiKey
apiKey is associated with metadata.openclaw.primaryEnv and is injected as
NOTION_API_KEY for the host agent run. Use an
OpenClaw SecretRef supported by the local gateway (env, file, exec, etc.).
Do not hardcode provider-specific secret paths in this shared skill.
Example SecretRef shape:
{
skills: {
entries: {
"diy-pc-ingest": {
apiKey: { source: "exec", provider: "your_notion_secret_provider", id: "value" }
}
}
}
}
Notes:
- The dependency must use Notion-Version
2025-09-03.
NOTIONCTL_PATH is an optional, non-secret path override. The dependency CLI
can also accept NOTION_TOKEN / NOTION_API_TOKEN, but this skill's OpenClaw
readiness gate still requires NOTION_API_KEY or the configured apiKey.
- Auth injection is scoped to the host agent run, not automatically to a
sandbox or a different node. Use the configured execution host and credential
delivery; do not copy secrets across hosts to make a missing gate pass.
- Preserve host-injected auth/proxy environment;
never extract credentials into chat, commands, logs or shell variables.
Data flow disclosure
- Local input: pasted receipts/spec notes are parsed locally.
- External enrichment (optional):
web_search/web_fetch may send partial product text to external web providers.
- Notion write path: records are queried/upserted via
notion-api-automation/scripts/notionctl.mjs.
Security rules:
- If user does not want external enrichment, skip
web_search/web_fetch and proceed with local extraction only.
- Use minimal-scope Notion integration permissions (only target DIY_PC data sources).
Canonical Notion targets
Use data_sources endpoints for schema/query, and pages endpoint for row creation.
IDs are documented in the DIY-PC Notion Targets table in the workspace AGENTS.md ## Tools section. Pass them as CLI arguments at runtime. See references/notion-ids.md for lookup and parent-ID rules.
Workflow (A: user pastes raw text)
Read the pasted text and decide target table per item:
- エンクロージャー: USB/RAID/HDDケース/ドック、ベイ数、JAN/型番、"安全な取り外し"表示名。
- ストレージ: HDD/SSD/NVMe/SATA/容量/シリアル/健康状態。
- PCConfig: CPU/GPU/RAM/PSU/MB/ケース/冷却/NIC/キャプチャ等。
Extract fields (best-effort). Prefer Japanese column names as they exist in each table.
Enrich specs using web_search/web_fetch when it reduces user work (e.g., bay count, interface, capacity, form factor). Keep it minimal; don't overfill.
Ask follow-up questions only for fields needed to avoid ambiguity or bad joins.
- ストレージ / PCInput: Serial missing is allowed. Omit it and proceed with
a provisional identity; do not ask solely to obtain a serial. Missing,
null, blank,
不明, シリアル不明, 未確認, 未取得, unknown, n/a
and - are treated as unknown, not shared serial keys.
- エンクロージャー: ベイ数 or USB/Thunderbolt/LAN unclear → ask.
- PCConfig: Identifier/型番 missing but needed to match existing row → ask.
- If a key collides with multiple rows, do not write; ask user.
Plan using live reads with scripts/notion_apply_records.js --plan (--dry-run is an alias; no mode also defaults to plan). Feed JSONL on stdin and explicit target IDs. Plan covers direct updates, upserts, archive and storage mirrors without write requests. Inspect each target/key/action, before/after, and blocked diagnostics. Missing keys/schema fields or multiple matches block the entire apply preflight; resolve them before applying.
Review scope against the user's existing authorization. Proceed without redundant approval for already-authorized changes. Ask only for unresolved identity/values or a concrete operation outside that scope, especially archive/overwrite. A plan is not authorization.
Apply the same JSONL with --apply and the same IDs. Apply re-reads the current ledger, preflights the whole batch, and rechecks each operation before writing. It fills empty fields unless overwrite=true; identical values are skipped even with overwrite. The plan is a preview, not an immutable transaction: do not run concurrent ingests for the same keys.
Inspect results, verify, then record success. Only status:applied counts as success after page read-back; skipped is unchanged. Keep blocked, failed and not_executed separate. Exit 1 / ok:false means the batch is not fully successful. A failed write/read-back can have an unverified remote effect; retain its ID if returned and reconcile before retrying. Never mark daily memory/progress complete before inspecting results.
Stop on rejection from either CLI or connector (isError, ok:false, exception or tool refusal). Do not switch tools/auth/routes to bypass it. Report only the returned reason; unknown causes stay unknown. For authorized resumption after the refusal/blocker is resolved, search/read the current original and replacement rows again, plan only pending changes, and avoid recreating already-created rows. Report skill implementation/deployment separately from the original ledger task's completion.
Commands
Run from the installed skill directory identified by SKILL.md (including owner-qualified paths). Use the dependency path resolved in Setup. Keep private input and plan output outside the repository.
node scripts/notion_apply_records.js --plan --notionctl-path "<RESOLVED_NOTIONCTL_PATH>" --storage-dsid <STORAGE_DS_ID> --storage-dbid <STORAGE_DB_ID> < records.jsonl
node scripts/notion_apply_records.js --apply --notionctl-path "<RESOLVED_NOTIONCTL_PATH>" --storage-dsid <STORAGE_DS_ID> --storage-dbid <STORAGE_DB_ID> < records.jsonl
Add --pcconfig-dsid / --pcconfig-dbid for mirrors. The script reads no config file and does not auto-discover database IDs.
Upsert keys (rules)
- ストレージ: Use a known
シリアル as the exact primary key. When unknown,
use exact Name + provided 購入日 / 価格(円) as the provisional key.
Search only unknown-serial candidates within those descriptive matches. A later
known serial first searches its exact key, then the same provisional fallback
to fill the existing row. Never join a different known serial by title.
- エンクロージャー:
取り外し表示名 (exact) else title/name.
- PCConfig:
(Name + Purchase Date) を複合キーとして扱う(exact)。重複ヒット時は書き込まず質問。
- PCInput: Use
(型番 + Serial + 名前) when Serial is known. Otherwise use
(型番 + 名前) + provided 購入日 / 価格(円) against unknown-Serial rows.
A later Serial can post-fill that provisional row without creating another.
- Required descriptive keys must be present; serial itself is optional for
storage and PCInput. Use a verified
page_id for direct post-fill if identity
remains unresolved. Exact queries follow pagination; incomplete queries block writes.
- If a key collides with multiple rows, do not write; ask user.
- Two serial-less items with the same provisional identity in one batch block
preflight rather than being silently folded together. Combine repeated edits
to one item into one record; give separate physical units distinct item names
(e.g. a bay/unit suffix), purchase details or verified page IDs. Do not invent
fake serial numbers. After a serial is filled, use it or the recorded page ID.
JSONL input format for the apply script
Each line is a JSON object:
{"target":"enclosure","title":"RATOC RS-EC32-R5G","properties":{"種別":"USBケース","接続":"USB","ベイ数":2,"普段つないでるPC":"RECRYZEN","購入日":"2026-01-18","購入店":"PCワンズ","価格(円)":8977,"取り外し表示名":"RS-EC32-R5G","メモ":"JAN: 4949090752191"}}
Optional control fields (for cleanup / manual fixes):
page_id (or id): update this Notion page directly (bypasses upsert matching)
archive: true: archive an existing matched or directly addressed page; never creates a row. An already archived direct page is skipped.
overwrite: true: allow overwriting existing values (including clearing with null)
- Unknown serial labels/blank input never erase a known serial. Only explicit
null together with page_id/id and overwrite:true clears that identity field.
Optional behavior flags:
mirror_to_pcconfig: true (only for target=storage): also create/update a pcconfig row for the installed component.
- requires:
現在の接続先PC, 購入日, Name
- Unknown serials leave mirrored
Spec empty so a later real serial can fill it.
Targets: enclosure | storage | pcconfig | pcinput
Serial-less storage example (registration does not require a serial question):
{"target":"storage","properties":{"Name":"Example SSD","購入日":"2026-10-05","価格(円)":5000,"メモ":"シリアル未確認"}}
Property value encoding:
- select/status: string name
- rich_text: string
- number: number
- date:
YYYY-MM-DD
- checkbox: boolean
- relation: array of page_ids (advanced; avoid unless needed)
Notes
- Always use Notion-Version
2025-09-03.
- Prefer
POST /v1/data_sources/{id}/query over /databases/{id}/query.
- Relation schema updates require
relation.data_source_id (not database_id).
Note (implementation)
- JS implementation is the default:
scripts/notion_apply_records.js
- Legacy Python implementation is reference-only:
scripts/_deprecated/notion_apply_records.py. Do not use it for plan/apply or as a rejection fallback.
Notion tooling
- Primary ingestion path is
scripts/notion_apply_records.js.
- For diagnostics, use the actual CLI path obtained by reading the installed
notion skill. Never substitute a fixed skills/<slug>/... path or use a
different credential/tool route after rejection.
1---2name: "diy-pc-ingest"3description: "Ingest pasted PC parts receipts or specs into Notion DIY_PC tables with classification, enrichment, verified upsert, and provisional records when serials are unknown."4metadata:5 source: https://skillmd.com/skills/nextaltair/diy-pc-ingest6 openclaw:7 requires:8 bins:9 - node10 env:11 - NOTION_API_KEY12 primaryEnv: NOTION_API_KEY13---1415# diy-pc-ingest1617## Setup (required)1819This skill is intended to be shared. Do **not** hardcode your Notion IDs or token in the skill.2021Resolve and read the installed Notion dependency before execution:2223- Its model-facing skill name is `notion`; its ClawHub package slug is24 `notion-api-automation`. Read it with `skills_read(name="notion")`.25 If unavailable, use `skills_search` to locate an eligible Notion CLI skill and26 read its complete instructions. A slug or directory name is not a skill name.27- Use the returned `SKILL.md` location to resolve `scripts/notionctl.mjs` on the28 same execution host as this skill. Do not assume both skills share a parent29 directory: workspace, grouped, managed, extra and revision paths can differ.30- Pass that absolute CLI path with `--notionctl-path` (preferred) or set the31 non-secret `NOTIONCTL_PATH` environment variable. Explicit paths take priority32 over the legacy sibling/scoped-root fallback; invalid explicit paths fail33 without searching another route.34- Check `node <resolved-notionctl-path> --help` for `api`, `--compact`,35 `--method`, `--path` and `--body-json`. The API bridge must return36 `{ok:true,result:...}`. Discovery/metadata does not guarantee this capability.37 Do not reinstall a working dependency just because this skill was updated.3839Only if the dependency is missing, use OpenClaw's install path for the intended40agent (replace `<agent-id>` with the configured agent, not a human profile ID):4142```bash43openclaw skills install @tristanmanchester/notion-api-automation --agent <agent-id>44```4546OpenClaw does not enforce cross-skill dependencies or optional environment47variables through `dependsOnSkills`, `optionalEnv` or `network` metadata fields.48The checks above and the data-flow rules below are part of this skill's procedure.49501) Read the `DIY-PC Notion Targets` table in the workspace `AGENTS.md` `## Tools` section for the data_source_id and database_id values for each target. Pass them as explicit CLI arguments:51- `--pcconfig-dsid`, `--pcconfig-dbid`52- `--pcinput-dsid`, `--pcinput-dbid`53- `--storage-dsid`, `--storage-dbid`54- `--enclosure-dsid`, `--enclosure-dbid`55562) Provide Notion auth for `notion-api-automation` (`notionctl`):57- env: `NOTION_API_KEY` (legacy shell/service env remains supported)58- OpenClaw config: `skills.entries["diy-pc-ingest"].apiKey`5960`apiKey` is associated with `metadata.openclaw.primaryEnv` and is injected as61`NOTION_API_KEY` for the host agent run. Use an62OpenClaw SecretRef supported by the local gateway (`env`, `file`, `exec`, etc.).63Do not hardcode provider-specific secret paths in this shared skill.6465Example SecretRef shape:6667```json568{69 skills: {70 entries: {71 "diy-pc-ingest": {72 apiKey: { source: "exec", provider: "your_notion_secret_provider", id: "value" }73 }74 }75 }76}77```7879Notes:80- The dependency must use Notion-Version `2025-09-03`.81- `NOTIONCTL_PATH` is an optional, non-secret path override. The dependency CLI82 can also accept `NOTION_TOKEN` / `NOTION_API_TOKEN`, but this skill's OpenClaw83 readiness gate still requires `NOTION_API_KEY` or the configured `apiKey`.84- Auth injection is scoped to the host agent run, not automatically to a85 sandbox or a different node. Use the configured execution host and credential86 delivery; do not copy secrets across hosts to make a missing gate pass.87- Preserve host-injected auth/proxy environment;88 never extract credentials into chat, commands, logs or shell variables.8990## Data flow disclosure9192- Local input: pasted receipts/spec notes are parsed locally.93- External enrichment (optional): `web_search`/`web_fetch` may send partial product text to external web providers.94- Notion write path: records are queried/upserted via `notion-api-automation/scripts/notionctl.mjs`.9596Security rules:97- If user does not want external enrichment, skip `web_search`/`web_fetch` and proceed with local extraction only.98- Use minimal-scope Notion integration permissions (only target DIY_PC data sources).99100## Canonical Notion targets101102Use **data_sources** endpoints for schema/query, and **pages** endpoint for row creation.103104IDs are documented in the `DIY-PC Notion Targets` table in the workspace `AGENTS.md` `## Tools` section. Pass them as CLI arguments at runtime. See [references/notion-ids.md](references/notion-ids.md) for lookup and parent-ID rules.105106## Workflow (A: user pastes raw text)1071081) **Read the pasted text** and decide target table per item:109 - **エンクロージャー**: USB/RAID/HDDケース/ドック、ベイ数、JAN/型番、"安全な取り外し"表示名。110 - **ストレージ**: HDD/SSD/NVMe/SATA/容量/シリアル/健康状態。111 - **PCConfig**: CPU/GPU/RAM/PSU/MB/ケース/冷却/NIC/キャプチャ等。1121132) **Extract fields** (best-effort). Prefer Japanese column names as they exist in each table.1141153) **Enrich specs using web_search/web_fetch** when it reduces user work (e.g., bay count, interface, capacity, form factor). Keep it minimal; don't overfill.1161174) **Ask follow-up questions** only for fields needed to avoid ambiguity or bad joins.118 - **ストレージ / PCInput**: Serial missing is allowed. Omit it and proceed with119 a provisional identity; do not ask solely to obtain a serial. Missing,120 null, blank, `不明`, `シリアル不明`, `未確認`, `未取得`, `unknown`, `n/a`121 and `-` are treated as unknown, not shared serial keys.122 - **エンクロージャー**: ベイ数 or USB/Thunderbolt/LAN unclear → ask.123 - **PCConfig**: Identifier/型番 missing but needed to match existing row → ask.124- If a key collides with multiple rows, do not write; ask user.1251265) **Plan using live reads** with `scripts/notion_apply_records.js --plan` (`--dry-run` is an alias; no mode also defaults to plan). Feed JSONL on stdin and explicit target IDs. Plan covers direct updates, upserts, archive and storage mirrors without write requests. Inspect each target/key/action, before/after, and blocked diagnostics. Missing keys/schema fields or multiple matches block the entire apply preflight; resolve them before applying.1271286) **Review scope** against the user's existing authorization. Proceed without redundant approval for already-authorized changes. Ask only for unresolved identity/values or a concrete operation outside that scope, especially archive/overwrite. A plan is not authorization.1291307) **Apply** the same JSONL with `--apply` and the same IDs. Apply re-reads the current ledger, preflights the whole batch, and rechecks each operation before writing. It fills empty fields unless `overwrite=true`; identical values are skipped even with overwrite. The plan is a preview, not an immutable transaction: do not run concurrent ingests for the same keys.1311328) **Inspect results, verify, then record success**. Only `status:applied` counts as success after page read-back; `skipped` is unchanged. Keep `blocked`, `failed` and `not_executed` separate. Exit 1 / `ok:false` means the batch is not fully successful. A failed write/read-back can have an unverified remote effect; retain its ID if returned and reconcile before retrying. Never mark daily memory/progress complete before inspecting results.1331349) **Stop on rejection** from either CLI or connector (`isError`, `ok:false`, exception or tool refusal). Do not switch tools/auth/routes to bypass it. Report only the returned reason; unknown causes stay unknown. For authorized resumption after the refusal/blocker is resolved, search/read the current original and replacement rows again, plan only pending changes, and avoid recreating already-created rows. Report skill implementation/deployment separately from the original ledger task's completion.135136## Commands137138Run from the installed skill directory identified by `SKILL.md` (including owner-qualified paths). Use the dependency path resolved in Setup. Keep private input and plan output outside the repository.139140```bash141node scripts/notion_apply_records.js --plan --notionctl-path "<RESOLVED_NOTIONCTL_PATH>" --storage-dsid <STORAGE_DS_ID> --storage-dbid <STORAGE_DB_ID> < records.jsonl142node scripts/notion_apply_records.js --apply --notionctl-path "<RESOLVED_NOTIONCTL_PATH>" --storage-dsid <STORAGE_DS_ID> --storage-dbid <STORAGE_DB_ID> < records.jsonl143```144145Add `--pcconfig-dsid` / `--pcconfig-dbid` for mirrors. The script reads no config file and does not auto-discover database IDs.146147## Upsert keys (rules)148149- **ストレージ**: Use a known `シリアル` as the exact primary key. When unknown,150 use exact `Name` + provided `購入日` / `価格(円)` as the provisional key.151 Search only unknown-serial candidates within those descriptive matches. A later152 known serial first searches its exact key, then the same provisional fallback153 to fill the existing row. Never join a different known serial by title.154- **エンクロージャー**: `取り外し表示名` (exact) else title/name.155- **PCConfig**: `(Name + Purchase Date)` を複合キーとして扱う(exact)。重複ヒット時は書き込まず質問。156- **PCInput**: Use `(型番 + Serial + 名前)` when Serial is known. Otherwise use157 `(型番 + 名前)` + provided `購入日` / `価格(円)` against unknown-Serial rows.158 A later Serial can post-fill that provisional row without creating another.159- Required descriptive keys must be present; serial itself is optional for160 storage and PCInput. Use a verified `page_id` for direct post-fill if identity161 remains unresolved. Exact queries follow pagination; incomplete queries block writes.162- If a key collides with multiple rows, do not write; ask user.163- Two serial-less items with the same provisional identity in one batch block164 preflight rather than being silently folded together. Combine repeated edits165 to one item into one record; give separate physical units distinct item names166 (e.g. a bay/unit suffix), purchase details or verified page IDs. Do not invent167 fake serial numbers. After a serial is filled, use it or the recorded page ID.168169## JSONL input format for the apply script170171Each line is a JSON object:172173```json174{"target":"enclosure","title":"RATOC RS-EC32-R5G","properties":{"種別":"USBケース","接続":"USB","ベイ数":2,"普段つないでるPC":"RECRYZEN","購入日":"2026-01-18","購入店":"PCワンズ","価格(円)":8977,"取り外し表示名":"RS-EC32-R5G","メモ":"JAN: 4949090752191"}}175```176177Optional control fields (for cleanup / manual fixes):178- `page_id` (or `id`): update this Notion page directly (bypasses upsert matching)179- `archive: true`: archive an existing matched or directly addressed page; never creates a row. An already archived direct page is skipped.180- `overwrite: true`: allow overwriting existing values (including clearing with null)181 - Unknown serial labels/blank input never erase a known serial. Only explicit182 `null` together with `page_id`/`id` and `overwrite:true` clears that identity field.183184Optional behavior flags:185- `mirror_to_pcconfig: true` (only for `target=storage`): also create/update a `pcconfig` row for the installed component.186 - requires: `現在の接続先PC`, `購入日`, `Name`187 - Unknown serials leave mirrored `Spec` empty so a later real serial can fill it.188189Targets: `enclosure | storage | pcconfig | pcinput`190191Serial-less storage example (registration does not require a serial question):192193```json194{"target":"storage","properties":{"Name":"Example SSD","購入日":"2026-10-05","価格(円)":5000,"メモ":"シリアル未確認"}}195```196197Property value encoding:198- select/status: string name199- rich_text: string200- number: number201- date: `YYYY-MM-DD`202- checkbox: boolean203- relation: array of page_ids (advanced; avoid unless needed)204205## Notes206207- Always use Notion-Version `2025-09-03`.208- Prefer `POST /v1/data_sources/{id}/query` over `/databases/{id}/query`.209- Relation schema updates require `relation.data_source_id` (not database_id).210211212## Note (implementation)213- JS implementation is the default: `scripts/notion_apply_records.js`214- Legacy Python implementation is reference-only: `scripts/_deprecated/notion_apply_records.py`. Do not use it for plan/apply or as a rejection fallback.215216217## Notion tooling218- Primary ingestion path is `scripts/notion_apply_records.js`.219- For diagnostics, use the actual CLI path obtained by reading the installed220 `notion` skill. Never substitute a fixed `skills/<slug>/...` path or use a221 different credential/tool route after rejection.