Content
76%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A strong, execution-first API skill: every recipe is runnable as written and the version-specific data-source/database distinctions are captured in a dedicated, high-value section. Its main gaps are the total absence of validation/verification feedback for write operations (which caps workflow clarity) and a description/frontmatter trigger clause, plus minor token trims in the repeated curl headers.
Suggestions
Add verification guidance for write operations, e.g. after creating/updating a page, fetch it with GET /v1/pages/{page_id} to confirm the change landed, and check the HTTP status / error 'object' in responses before proceeding.
Extract the Property Types reference and possibly the rarer operations (create data source) into a references/ file, keeping SKILL.md as a lean overview with clearly signaled one-level-deep links.
State the authorization failure mode (401/403 when a page hasn't been shared with the integration) and its fix, since sharing is the most common setup pitfall and currently only appears as a setup step with no error-recovery loop.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is largely lean — curl recipes with minimal prose and a 'Key Differences' section that conveys exactly the non-obvious, version-specific knowledge. It is not a 5 because of small trims available, e.g. 'This skill uses 2025-09-03 (latest)' and repeating the full three-header block verbatim in every example where the setup already establishes it. It is clearly above level 3, which calls for unnecessary explanation of things Claude already knows. | 4 / 5 |
Actionability | Every operation is a complete, copy-paste-ready curl command with real headers, endpoints, and JSON payloads (search, get page, get blocks, create page, query, create data source, update, append blocks), plus a concrete property-type cheat sheet. This matches the level-5 anchor: fully executable commands covering the common cases. | 5 / 5 |
Workflow Clarity | Setup is a clear numbered sequence and each operation is unambiguous, but there are no validation or verification steps for the write operations (creating pages, updating properties, appending blocks) and no error-recovery guidance. Per the rubric's cap — missing validation in workflows involving database/data-source operations, which the scoring notes explicitly list — workflow clarity cannot exceed 3. It is not level 2 because the sequences present are well defined and concrete, not gappy. | 3 / 5 |
Progressive Disclosure | No bundle files exist, and the body is well organized into clearly headed sections (Setup, API Basics, Common Operations, Property Types, Key Differences, Notes) with each block easy to locate. It is not level 5 because at ~150 lines the Property Types list and the full operation catalogue could arguably live in a separate reference file, and no references/navigation to split content are provided; it is not level 3 because nothing that clearly belongs elsewhere is inlined and no references are buried. | 4 / 5 |
Total | 16 / 20 Passed |