notion

Notion API for creating and managing pages, databases, and blocks.

1.57x

Quality

52%

Does it follow best practices?

Impact

99%

1.57x

Average score across 3 eval scenarios

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/notion/SKILL.md

Quality

Discovery

40%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description identifies a clear domain (Notion API) and lists high-level resource types (pages, databases, blocks), giving it reasonable distinctiveness. However, it lacks a 'Use when...' clause, provides only surface-level action descriptions, and misses natural trigger term variations that users might employ when requesting Notion-related tasks.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to create, update, query, or manage content in Notion, or mentions Notion pages, databases, or workspace organization.'

Expand the list of concrete actions beyond 'creating and managing' — include specific operations like querying databases, updating page properties, appending blocks, searching content, and archiving pages.

Include natural trigger term variations such as 'Notion workspace', 'Notion wiki', 'Notion table', or 'Notion integration' to improve keyword coverage.

Dimension	Reasoning	Score
Specificity	Names the domain (Notion API) and some actions (creating and managing pages, databases, and blocks), but doesn't list specific concrete actions like querying, updating properties, archiving, or searching.	2 / 3
Completeness	Describes what it does (Notion API for creating/managing pages, databases, blocks) but completely lacks a 'Use when...' clause or any explicit trigger guidance, which per the rubric caps completeness at 2, and the 'what' is also fairly thin, placing this at 1.	1 / 3
Trigger Term Quality	Includes 'Notion', 'pages', 'databases', and 'blocks' which are relevant keywords, but misses common user variations like 'Notion workspace', 'Notion integration', 'wiki', or task-related terms users might naturally say.	2 / 3
Distinctiveness Conflict Risk	The mention of 'Notion API' creates a clear niche that is unlikely to conflict with other skills; Notion is a specific product and the API focus further narrows the scope.	3 / 3
	Total	8 / 12 Passed

Implementation

64%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This is a solid, actionable API reference skill with fully executable curl examples covering all major Notion operations. Its main weaknesses are the repetitive curl headers inflating token count, the lack of error handling/validation guidance for API operations, and the monolithic structure that could benefit from splitting reference material into separate files.

Suggestions

Define the curl headers once as a reusable template or shell variable at the top, then reference it in subsequent examples to reduce repetition (e.g., define NOTION_HEADERS and use curl $NOTION_HEADERS in examples).

Add a brief error handling section showing how to check API response codes and handle common errors (401 unauthorized, 404 not found, 429 rate limited) with a retry pattern.

Split the Property Types reference and Key Differences sections into separate bundle files (e.g., PROPERTY_TYPES.md, VERSION_CHANGES.md) and link to them from the main skill.

Dimension	Reasoning	Score
Conciseness	The content is mostly efficient with concrete examples, but the repeated curl headers across every example add significant redundancy. A single template with a note to reuse it would save many tokens. The property types reference section is useful but could be more compact.	2 / 3
Actionability	Every operation includes a fully executable curl command with proper headers, JSON payloads, and realistic property structures. The setup instructions are concrete with exact file paths and commands. The property types reference provides copy-paste-ready JSON formats.	3 / 3
Workflow Clarity	The setup steps are clearly sequenced (1-4), and operations are well-organized. However, there are no validation checkpoints — no guidance on checking API responses for errors, handling rate limits, or verifying that operations succeeded. For an API skill involving data creation/modification, error handling guidance would strengthen this.	2 / 3
Progressive Disclosure	The content is well-structured with clear section headers, but it's a fairly long monolithic file. The property types reference and version differences sections could be split into separate reference files. No bundle files exist to offload detailed reference material.	2 / 3
	Total	9 / 12 Passed

Validation

72%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 8 / 11 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning
metadata_field	'metadata' should map string keys to string values	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	8 / 11 Passed

Repository: deepgram/dglabs-deepclaw
Commit: ec8d4f8

Reviewed: about 8 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.