notion

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

Quality

64%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.trae/openclaw-skills/notion/SKILL.md

Quality

Content

76%Weight 40%Scale 1-5

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

The skill is highly actionable with copy-paste curl examples and tight, non-padded prose, but lacks verification checkpoints after destructive database/page operations and is a single ~150-line file with no progressive disclosure into reference files.

Suggestions

Add a validation step after create/update operations, e.g. 'After creating a page, GET /v1/pages/{id} to confirm it exists and properties were applied correctly.'

Move the version-specific 'Key Differences in 2025-09-03' and 'Property Types' sections into a reference file (e.g. references/data-sources-2025.md) and link from SKILL.md to reduce time-sensitive repetition and improve progressive disclosure.

Define the Notion-Version header once (e.g. via a shell variable) instead of repeating the literal '2025-09-03' in every curl block, so version bumps touch one place.

Dimension	Reasoning	Score
Conciseness	The body is lean with no padding about what Notion or APIs are, but the time-sensitive version string '2025-09-03' is repeated in every curl example rather than being isolated in a deprecated/version section, so per the rubric conciseness is penalized below 5.	4 / 5
Actionability	All examples are fully executable, copy-paste-ready curl commands covering search, get page, get blocks, create/query/update pages and data sources, plus a property-types reference with concrete JSON formats, matching the anchor for copy-paste-ready code covering common cases.	5 / 5
Workflow Clarity	Setup is a clear numbered sequence and operations are well-organized, but the skill performs database/page create/update operations with no verify-after-write validation checkpoint; per the rubric, missing feedback loops for database operations caps workflow clarity at 3.	3 / 5
Progressive Disclosure	Content is well-organized into clearly signaled sections (Setup, API Basics, Common Operations, Property Types, Key Differences, Notes) with no nested references, but the skill exceeds 50 lines and sections like Property Types / Key Differences could be split into separate reference files, so it sits below the 5 anchor.	4 / 5
	Total	16 / 20 Passed

Description

53%Weight 40%Scale 1-5

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 is specific to Notion and names concrete object types, but it omits any explicit 'Use when...' trigger guidance, capping completeness and trigger-term quality. Adding a trigger clause with natural user phrases would lift the weaker dimensions.

Suggestions

Add a 'Use when...' clause naming natural user triggers, e.g. 'Use when creating or updating Notion pages, databases, or blocks, or when the user mentions Notion notes/docs/workspace.'

Replace the generic verb 'managing' with specific concrete actions (e.g. 'creating, reading, updating, and searching pages, databases, and blocks').

Include common synonyms/extensions users say ('Notion docs', 'Notion workspace', 'Notion database') to improve trigger-term coverage.

Dimension	Reasoning	Score
Specificity	The phrase 'creating and managing pages, databases, and blocks' names the domain and one concrete action ('creating') plus a vague one ('managing') across three object types, matching the anchor for 1-2 concrete actions without comprehensive coverage. 'Managing' is generic and not the multiple specific actions needed for a 4.	3 / 5
Completeness	It clearly answers 'what' (Notion API for creating/managing pages, databases, blocks) but has no 'Use when...' or equivalent trigger guidance, so per the rubric a missing 'when' clause caps completeness at 3.	3 / 5
Trigger Term Quality	Terms like 'Notion API', 'pages', 'databases', and 'blocks' are domain-relevant, but 'Notion API' is technical jargon and natural user phrases ('Notion page', 'Notion docs', 'add to Notion', 'Notion workspace') are missing, matching the anchor for some relevant keywords missing common variations.	3 / 5
Distinctiveness Conflict Risk	'Notion API' is a clear, specific niche with minimal overlap risk, sitting above the 3 anchor (somewhat specific, possible overlap) but below the 5 anchor which requires explicit distinct trigger phrases that are absent here.	4 / 5
	Total	13 / 20 Passed

Validation

81%

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 — 13 / 16 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	13 / 16 Passed

Repository: huangruiteng/CS-Notes
Path: .trae/openclaw-skills/notion/SKILL.md
Commit: 43eb317

Reviewed: 3 days 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.