Operations · Claude Code skill

Notion Page Writer skill and the Yalc Framework

The single source of truth for Notion writes in Yalc workflows. Knows the 40-page batch limit, the format conventions, and the right MCP tool per operation.

Yalc Fit Score
10/10
License
MIT (Yalc)
Batch size
40 pages max
Conventions
Earleads format rules
Last reviewed
2026-04-29
Trigger phrases

Say this to fire the Notion Page Writer skill

Any of these natural language phrases activates the skill inside Claude Code.

writing to Notion
adding a row to a Notion database
updating a Notion page
appending content to a Notion page
creating a Notion page
inserting content into Notion
logging results to Notion
What it does

Notion Page Writer, plainly

The Notion Page Writer skill is the canonical Yalc wrapper for any Notion write operation. It encapsulates the learned Earleads playbook: how to discover the right MCP tool for an operation (create-pages, update-page, append-content), how to resolve page and database and data-source IDs, and how to construct correct payloads (especially Earleads' format conventions for checkboxes, dates, and multi-selects).

For Yalc workflows, this skill is the gateway for any non-trivial Notion write. Direct Notion MCP calls work for simple cases but bypass the playbook (40-page batch limit, format conventions, schema discovery). The skill is the abstraction that prevents the common errors (timeout on large batches, validation errors on multi-selects, ID confusion between pages and data sources).

Where it slots in

Position in the GTM operating system

Intake
→
Enrich
→
Score
→
Route
→
Draft
→
Send
→
Listen

The Notion Page Writer sits at the **route** node for any Yalc workflow that ends in "write to Notion". It chains downstream of every other Yalc skill that produces structured output (qualification, scraping, monitoring, repurposing).

The skill enforces three guardrails: 40 pages max per create call (larger batches timeout), schema discovery before write (validate property types upfront), and Earleads format conventions ("__YES__" for checkbox true, ISO 8601 for dates, JSON array string for multi-selects).

The Yalc Framework

Running the Notion Page Writer skill end to end

Workflow position

The Notion write gateway. Yalc invokes this skill whenever a workflow needs to push data to Notion. Output is a confirmation log with success counts and any failures.

Required inputs

  • → The target Notion page or database (URL, page ID, or data source ID)
  • → The data to write (rows, content, properties)
  • → The operation type (create, update, append)
  • → Notion API credential

Outputs

  • → Confirmation log with success and failure counts
  • → Per-row error details if any rows fail validation
  • → Notion URLs for newly created pages (when applicable)

Chaining recommendations

UpstreamAny Yalc skill output → notion-page-writer (writeback)
DownstreamNotion state change → next workflow trigger (via webhook handler)

Anti patterns to avoid

Don't push more than 40 pages per `create-pages` call. Notion's bulk API times out above 40. The skill chunks larger jobs automatically; bypassing the skill bypasses the chunking.
Don't write multi-select values as plain strings. Notion expects JSON array strings; the skill enforces this. Direct MCP calls without the skill often fail validation here.
Don't write checkbox values as `true` or `false` literals. Earleads convention uses `__YES__` and `__NO__` strings (legacy reasons, but consistent across all Yalc workflows).
Operator take

Pros, cons, who it's for

Pros

  • Encapsulates the 40-page batch limit (the most common Yalc Notion bug)
  • Enforces Earleads format conventions across all writes
  • Schema discovery prevents validation errors at runtime
  • Resolves IDs by name for cleaner Yalc prompts
  • Used in production by 8+ daily monitoring agents and on-demand reports

Cons

  • Notion-specific. For Airtable or other databases, this skill doesn't apply.
  • Requires NOTION_API_KEY env var per Yalc workspace
  • The 40-page limit is empirical (not officially documented by Notion); if Notion raises it, the skill would still chunk to 40
  • Schema discovery latency on first call to a new DB (caching helps subsequent calls)

Who it's for

  • Yalc operators using Notion as CRM, content tracker, or campaign DB
  • Earleads' daily monitoring and repurposing agents (production)
  • Any GTM workflow that writes structured data to Notion at volume
Dependencies

What this skill expects to find

MCP servers

Environment variables

The skill resolves page and database IDs by name when possible. For ambiguous names, it requires the explicit data source ID. Schema discovery cached per-database for the session to avoid repeated introspection.

Related

The Notion Page Writer ecosystem inside Yalc

Notion MCP
Underlying transport. The skill wraps the MCP with batch limits and conventions.
→
Alternatives

Skills that overlap

Direct Notion MCP calls
Skip the skill for simple one-off writes. The MCP is sufficient when batch and format aren't concerns.
→
Notion's REST API directly
Switch when running headless cron jobs outside Claude Code.
→
Airtable Page Writer
Switch when the target is Airtable. The pattern transfers but specifics differ.
→
FAQ

Frequently asked

Why a 40-page batch limit?

Empirical Earleads finding. Notion's bulk create-pages API frequently times out above 40 pages per call, especially when properties include rich text or relations. 40 is the safe ceiling. The skill auto-chunks larger jobs.

What are the Earleads format conventions?

Checkboxes use `__YES__` or `__NO__` strings (legacy from earlier Notion API versions). Dates use ISO 8601 with explicit time zone. Multi-selects use JSON array strings (`'["tag1", "tag2"]'`), not Python or JS arrays. Documented at the top of the skill's SKILL.md.

Can the skill update existing pages?

Yes. update-page operation takes a page ID and partial properties. The skill handles the property type translation automatically (which is what differs between create and update calls).

How does schema discovery work?

On first write to a database in a session, the skill queries the database schema (property names and types) and caches it. Subsequent writes use the cache. For schema changes mid-session, restart the Claude Code session to invalidate the cache.

Does the skill handle relations and rollups?

Yes for relations. The skill resolves related page IDs by name when given. Rollups are derived properties; the skill doesn't write to them (Notion calculates them automatically).

What if Notion's API rate limits me?

The skill respects Notion's rate limits (3 requests per second average) and includes exponential backoff on 429 errors. For large batches, you may see noticeable runtime; that's intentional.

Get the Notion Page Writer skill

Clone the Yalc skill set, drop in your env, run from your next Claude Code session.

gh repo clone Othmane-Khadri/YALC-the-GTM-operating-system && cp -r YALC-the-GTM-operating-system/.claude/skills/notion-page-writer ./.claude/skills/
View on GitHub We deploy it for you
Last reviewed 2026-04-29 by Othmane Khadri