notion

Notion REST capability: search, read pages, create pages, read and append blocks, and query databases.

Ported from kernel snappy-notion in Phase 0.5. See state/lib/notion.ts for the full API surface.

Steps

• search() - see state/lib/notion.ts
• getPage() - see state/lib/notion.ts
• createPage() - see state/lib/notion.ts
• getBlockChildren() - see state/lib/notion.ts
• appendBlocks() - see state/lib/notion.ts
• queryDatabase() - see state/lib/notion.ts

Eval

Actor: the exported functions in state/lib/notion.ts. Auditor: none wired yet - eval is manual (Robert review). File a state/log/pending-eval.ndjson row on each run.

Score convention:

Gotchas

via the Phase 0.5 driver. Only these rewrites were applied: already in state/lib/)

1. realpathSync(process.argv[1]) CLI guard wrapped in try/catch

• See the kernel SKILL.md for the original long-form guidance if you need it

(read-only reference at the kernel path above).

Eval policy

This skill is prose. Wire a deterministic auditor and set eval: auto to score it automatically.

Rubric

criteria:
  - name: notion_result_nonzero
    kind: deterministic
    check: "Called function returns a non-empty result. search() returns {results: [...]}, array.length > 0. getPage/queryDatabase return object with id + properties. createPage returns {id, ...}."
  - name: api_success_code
    kind: deterministic
    check: "HTTP response code is 200/201 (success). No 401/403 (auth), 429 (rate limit), or 5xx errors in the execution log."
  - name: no_fallback_path
    kind: deterministic
    check: "Eval verb is NOT 'fallback'|'auth-failed'|'rate-limited'. Primary Notion API path was used (not local cache or degraded mode)."
  - name: if_fallback_then_capped
    kind: deterministic
    check: "If auth/rate-limit causes fallback path, score is capped at 0.5 max regardless of fallback success."
  - name: data_structure_valid
    kind: judge
    check: "Result schema matches Notion API docs. search results include object with title and block-type fields. Pages include properties object."

notion - loader

Per-turn rules for the notion skill. Full reference: state/skills/notion/SKILL.md. Do not skip these.

Compound Response Pattern (MANDATORY)

When notion/notes intent fires, you MUST compose a structured surface - NOT flat prose.

Steps:

1. Fetch recent pages via state/lib/notion.ts:

   npx tsx state/lib/notion.ts search "" --limit 10

Or import: search("") from state/lib/notion.ts (re-exports from state/lib/docs.ts).

1. Compose via compose_inline:

root = Card([
  CardHeader("Notion - Recent"),
  Stack([
    Callout("Recently Edited", [...top 5 page titles as ListBlock items, or "No recent pages found"...]),
    Callout("Databases", [...key databases found: projects, tasks, notes, etc...]),
    Card([
      TextInput("New Page Title", @Set($pageTitle, @Input)),
      Button("Create Note", Mutation("invoke_skill_verb", {slug: "notion", verb: "create-page", apply: true, args: {title: $pageTitle}}))
    ])
  ]),
  FollowUpBlock([
    SnappyFollowUpItem("create a new note about today's work", "New note"),
    SnappyFollowUpItem("search notion for [topic from context]", "Search Notion"),
    SnappyFollowUpItem("summarize my project notes", "Summarize projects"),
  ])
])
$pageTitle = ""

1. Always include FollowUpBlock even if pages are empty.

Critical Rules

_(no failures recorded yet - this skill is a Phase 0.5 mechanical port from snappy-notion with no hard-won rules. Marked LEGACY in the .md frontmatter - confirm the workflow actually needs Notion before reaching for this; most current substrate uses local files + Xano. Read state/skills/notion/SKILL.md and state/lib/notion.ts before invoking.)_

Commands

| ui model | live composition via compose_inline, persisted as artifact lang_body, reopened with OpenArtifact | |invoke: import from state/lib/notion.ts - search(), getPage(), createPage(), getBlockChildren(), appendBlocks(), queryDatabase() |eval log: state/log/pending-eval.ndjson (manual review until shape gate added)

Known Pitfalls

• Marked LEGACY - most workflows have moved off Notion. Verify the user actually wants Notion-targeted output before invoking
• Skill frontmatter says eval: shape but no auditor wired - log to pending-eval.ndjson

Self-Test

An agent reading this should correctly:

1. [ ] Question whether Notion is really the target before invoking (it's marked legacy)?
2. [ ] Use env("NOTION_TOKEN") (or whatever the lib expects) rather than bash credential fallback?
3. [ ] Log to pending-eval.ndjson because no shape auditor exists yet?

Found a gap? Edit this file. <!-- footer-injection-point -->