notion

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

Quality

61%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Critical

Do not install without reviewing

Fix and improve this skill with Tessl

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

Quality

Content

65%

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

The body is highly actionable with copy-paste-ready commands for both the ntn CLI and HTTP paths, and its workflows are well sequenced. Its main weaknesses are conciseness (repeated headers, inline time-sensitive dates) and progressive disclosure (an existing reference file is never linked, and reference-grade content is inlined).

Suggestions

Factor the repeated curl header block into a single shared snippet and reference it, or show headers once and note they apply to every request, to cut token overhead.

Link the existing `references/block-types.md` from the body (e.g. in the Property Types or append-blocks section) and move the per-endpoint curl reference there so the body stays an overview.

Add a quick verification step after destructive/batch operations (e.g. re-read the page after archiving or appending blocks) to lift workflow clarity.

Consolidate scattered time-sensitive statements (version, free-through date, platform support dates) into one clearly labeled section.

Dimension	Reasoning	Score
Conciseness	It assumes Claude's competence (no explanations of what Notion or an API is) and stays command-focused, but every curl example repeats the full header block and time-sensitive dates ('2025-09-03', 'Free through August 11, 2026', 'as of May 2026') are scattered inline rather than isolated, fitting 'Mostly efficient but... could be tightened' rather than the lean score-3 anchor.	2 / 3
Actionability	Every section provides complete, executable commands — copy-paste curl snippets, ntn invocations, and a full TypeScript Worker scaffold — matching 'Fully executable code/commands; specific examples; copy-paste ready'.	3 / 3
Workflow Clarity	Multi-step flows (Setup 1-3, 3-step file upload, worker new→edit→deploy) are clearly sequenced and setup includes an `ntn --version` verify step, but destructive/batch operations like `archived:=true` and bulk block appends lack any read-back verification, so per the scoring notes workflow_clarity is capped at 2.	2 / 3
Progressive Disclosure	The body is well sectioned with headers and keeps references one level deep, but the provided `references/block-types.md` is never linked or signaled from the body and large API reference material (Property Types, per-endpoint curl) is inline, matching 'references present but not clearly signaled; content that should be separate is inline'.	2 / 3
	Total	9 / 12 Passed

Description

57%

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 terse, distinctive, and names concrete Notion capability areas, but it reads as a noun list with no action verbs and omits any explicit 'Use when...' trigger guidance. Adding a trigger clause and a few user-natural variations would lift the weaker dimensions.

Suggestions

Append an explicit 'Use when...' clause, e.g. 'Use when the user asks to read, search, create, or update Notion pages, databases, or notes, or to build Notion Workers.'

Add a verb or two to surface concrete actions (read/search/create/query/update) instead of only listing objects.

Include common user-natural variations such as 'notes', 'workspace', or 'databases/data sources' to broaden trigger coverage.

Dimension	Reasoning	Score
Specificity	Names the domain ('Notion API') and concrete capability objects ('pages, databases, markdown, Workers') plus the two interfaces, but lists nouns rather than action verbs, matching the score-2 anchor 'Names domain and some actions, but not comprehensive' rather than the verb-rich score-3 example.	2 / 3
Completeness	It clearly states what the skill does ('pages, databases, markdown, Workers') but contains no 'Use when...' clause or equivalent explicit trigger guidance, so per the judging guidelines completeness is capped at 2 ('Has what, but when is missing or only implied').	2 / 3
Trigger Term Quality	'Notion', 'pages', 'databases', 'markdown' are natural terms users say, but common variations like 'notes', 'docs', 'workspace', or 'tasks' are absent and 'ntn CLI'/'Workers' lean technical, fitting 'Some relevant keywords but missing common variations' rather than the broad score-3 coverage.	2 / 3
Distinctiveness Conflict Risk	The 'Notion' / 'ntn CLI' / 'Workers' niche is specific and clearly distinguishable from other skills, making it unlikely to trigger for the wrong skill, matching the score-3 anchor 'Clear niche with distinct triggers'.	3 / 3
	Total	9 / 12 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: d0d116b

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.