notion

Notion API + ntn CLI: pages, databases, markdown, Workers.

Quality

60%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./skills/productivity/notion/SKILL.md

Quality

Content

65%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 content is highly actionable with comprehensive executable examples and clear sequencing, but it is verbose, inlines large reference blocks that belong in separate files, and lacks validation feedback loops for its destructive and batch operations.

Suggestions

Move the duplicated curl/ntn operation catalog, the Property Types list, and the Notion-Flavored Markdown spec into reference files (alongside references/block-types.md) and link to them from the body to improve progressive disclosure and reduce token cost.

Add explicit validate-then-retry checkpoints for destructive and batch operations (e.g., verify a page exists before PATCHing archived, confirm an upload completed before referencing file_upload_id, re-check worker logs on deploy failure).

Isolate time-sensitive facts (Notion-Version date, the August 11 2026 free-tier cutoff, 'as of May 2026' platform notes) in a dedicated 'Version / time-sensitive' or 'Deprecated' section so dated content does not penalize conciseness.

Dimension	Reasoning	Score
Conciseness	The body is mostly dense and assumes competence, but it is long (~430 lines) with redundant curl/ntn repetitions, mild over-explanatory asides, and time-sensitive items (Notion-Version date, 'Free through August 11, 2026') not isolated in a deprecated section — fitting 'Mostly efficient but includes some unnecessary explanation or could be tightened.'	3 / 5
Actionability	Copy-paste-ready commands and complete JSON payloads are provided for every common operation across both the ntn CLI and curl paths, plus a decision table and Worker scaffold — matching 'Fully executable; copy-paste ready code or commands; specific examples cover the common cases.'	5 / 5
Workflow Clarity	Setup, the 3-step file-upload flow, and the worker build flow are sequenced with some checkpoints, but destructive/batch operations (PATCH archived, block appends, deploys) lack explicit validate-then-retry feedback loops, so the rubric's cap of 3 applies.	3 / 5
Progressive Disclosure	Section headers, a path-choosing table, and a one-level-deep reference (references/block-types.md) provide structure, but most reference-grade material (every curl example, property types, the markdown-flavor spec, the full Workers guide) is inlined rather than split — fitting 'Some structure but could be better organized; content that should be separate is inline.'	3 / 5
	Total	14 / 20 Passed

Description

56%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 compact and names the right domain and tools but lacks action verbs and any 'Use when...' trigger clause, leaving its 'when' guidance implicit. It is distinctive but underspecified on capabilities and triggers.

Suggestions

Add explicit action verbs (e.g., 'Search, read, and create Notion pages and databases; convert pages to Markdown; upload files; build Notion Workers') to raise specificity.

Append a 'Use when...' clause naming concrete triggers (e.g., 'Use when the user asks to read or edit Notion pages, query databases, convert Notion content to Markdown, or deploy Notion Workers').

Include natural synonyms and product cues (e.g., 'Notion workspace', 'notes', 'Notion database') to broaden trigger coverage.

Dimension	Reasoning	Score
Specificity	The description names the domain and tools ("Notion API + ntn CLI", "pages, databases, markdown, Workers") but uses no action verbs, so it conveys what is targeted without what the skill does — matching 'Names the domain but actions are minimal or generic.'	2 / 5
Completeness	A compressed 'what' is present, but there is no 'Use when...' or equivalent trigger guidance, so per the rubric a missing 'when' clause caps completeness at 3.	3 / 5
Trigger Term Quality	Natural keywords users would say are present (Notion, pages, databases, markdown, Workers), but synonyms and extension-style cues are missing, fitting 'Good keyword coverage; a few natural terms missing.'	4 / 5
Distinctiveness Conflict Risk	Naming Notion plus its specific ntn CLI gives a clear niche with minimal conflict risk, though the generic term 'Workers' and absence of an explicit trigger phrase keep it just below 5.	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: NousResearch/hermes-agent
Path: skills/productivity/notion/SKILL.md
Commit: 6327930

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.