Content
67%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, actionable reference: every workflow names exact tools, parameters, and failure modes with concrete JSON examples and pagination handling, and it assumes Claude's competence rather than teaching Notion basics. Its main weaknesses are redundancy between the workflows, the Known Pitfalls section, and the Quick Reference table, plus missing example payloads for block and comment content.
Suggestions
Consolidate the duplicated pitfalls: keep the per-workflow Pitfalls lists and cut the overlapping "Known Pitfalls" entries (case-sensitive property names, read-only formula/rollup fields, pagination) that already appear above, or vice versa.
Add a short example payload for `content_blocks` (one heading + one paragraph block object) and for `rich_text` in comments, since those are the two parameters whose structure is not inferable from the skill.
Drop the redundant Quick Reference rows that restate tools and parameters already covered in the workflows, or replace the table with only the tools not mentioned in any workflow section (e.g. NOTION_DUPLICATE_PAGE).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and assumes Claude already knows Notion API concepts, but it is noticeably duplicated: the Quick Reference table restates tool slugs and parameters already given in the five workflows, and the "Known Pitfalls" section repeats pitfalls stated earlier (case-sensitive property names, read-only formula fields, pagination). It could be tightened to a 4 by consolidating these. | 3 / 5 |
Actionability | Guidance is concrete and executable for an MCP-driven skill: exact tool names in sequenced order, exact parameter names with the critical gotcha ("Use `content_blocks` parameter, NOT `child_blocks`"), copy-ready JSON filter syntax, and pagination mechanics. Minor gaps keep it from a 5 — no example payload for `content_blocks` block objects or the `rich_text` array. | 4 / 5 |
Workflow Clarity | Each workflow has a numbered tool sequence with [Prerequisite] markers, the setup includes explicit verification ("Confirm connection status shows ACTIVE before running any workflows"), and pitfalls provide error-recovery feedback (404 → wrong database_id, 400 → schema mismatch, unarchive via UPDATE_PAGE). It is not a 5 because destructive operations (ARCHIVE_NOTION_PAGE, DELETE_BLOCK, REPLACE_PAGE_CONTENT) lack an explicit verify-before-acting checkpoint, though their reversibility is clearly flagged. | 4 / 5 |
Progressive Disclosure | The skill is a single well-organized file with clear section headers, per-task subsections, and a clearly signaled external docs link — no nested or buried references. It is not a 5 because the ~220-line body carries reference material (the 21-row Quick Reference table) that overlaps the workflow sections and could be consolidated or split, and the skill exceeds the under-50-line simple-skill threshold. | 4 / 5 |
Total | 15 / 20 Passed |