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.
The body is a strong, example-driven API skill: eight fully executable curl commands with concrete payloads, exact property formats, and a helpful section on version-specific gotchas (data sources vs. databases, dual IDs). Its weaknesses are the absence of validation/verification steps for write operations and minor token inefficiencies (repeated headers, a pinned "latest" version date).
Suggestions
Add validation steps for write operations, e.g., after creating a page, check the response for the returned page ID and confirm the object type before proceeding; retry or inspect the error payload on failure.
State the auth headers once (they are already shown in "API Basics") and trim them from the individual operation examples to reduce repetition.
Move the pinned Notion-Version date into a clearly labeled version note (or a 'changes from older versions' framing) so the "(latest)" claim does not silently go stale.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and assumes Claude's competence — no padding, no explaining what Notion is, and every section delivers operational content ("All requests need", "Common Operations", "Property Types"). Minor inefficiencies keep it below the top anchor: the three auth headers are repeated verbatim in all eight curl examples, and the pinned "Notion-Version: 2025-09-03" labeled "(latest)" is time-sensitive information not placed in a deprecated/old-patterns section. | 4 / 5 |
Actionability | Every operation is a complete, copy-paste-ready curl command with a concrete JSON payload: search, get page, get blocks, create page, query a data source, create a data source, update page properties, and append blocks. The "Property Types" section gives exact payload formats (e.g., `{"select": {"name": "Option"}}`), fully covering the common cases — matching the top executable-guidance anchor rather than the "minor gaps" anchor below. | 5 / 5 |
Workflow Clarity | Setup is a clear numbered sequence (create integration → copy key → store it → share pages) and operations are well organized, but there are no validation or verification steps after write operations (create/update pages, create data sources) — no guidance to check the response, confirm the created page's ID, or retry on error. Per the rubric's cap for database/batch operations without feedback loops, workflow clarity is capped at 3 rather than scoring 4 for the otherwise clear sequencing. | 3 / 5 |
Progressive Disclosure | The skill is a single self-contained file with well-organized, clearly headed sections (Setup, API Basics, Common Operations, Property Types, Key Differences, Notes) that are easy to navigate, and there are no buried or nested references. It falls short of the top anchor because content such as the property-type table and the full set of operation examples could arguably be split into one-level-deep reference files for a leaner core SKILL.md. | 4 / 5 |
Total | 16 / 20 Passed |