schema-markup

When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user mentions "schema markup," "structured data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "product schema," "review schema," or "breadcrumb schema." For broader SEO issues, see seo-audit.

Quality

80%

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 ./.claude/skills/schema-markup/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 body is well-structured with good progressive disclosure and a clean reference link, but it leans on generic principles rather than fully executable inline examples and lacks an explicit validate-fix-retry feedback loop for a task that routinely produces invalid markup.

Suggestions

Replace the placeholder Output Format block with at least one complete, copy-paste-ready JSON-LD example for a common type (e.g., Article or Product) so the skill is actionable without opening the reference.

Add an explicit validation checkpoint with a fix-retry loop: run the Rich Results Test, list common failure modes, and instruct to re-validate until clean before deploying.

Trim the 'Core Principles' section, which restates guidance Claude already knows, to improve token efficiency.

Dimension	Reasoning	Score
Conciseness	Mostly efficient with well-organized tables and short bullets, but sections like 'Core Principles' restate obvious guidance ('Don't markup content that doesn't exist', 'Test before deploying') that Claude already knows.	4 / 5
Actionability	Provides a schema-type table with required properties and a generic @graph template, but lacks complete executable JSON-LD examples inline for common cases; full examples are offloaded to the reference file and the 'Output Format' block is a skeleton with placeholders.	3 / 5
Workflow Clarity	The Initial Assessment and Validation sections give a rough sequence (assess -> implement -> validate), but there is no explicit validation checkpoint or fix-retry loop tying the Rich Results Test back into the workflow before deploy.	3 / 5
Progressive Disclosure	Clear one-level-deep reference: full JSON-LD examples are offloaded to references/schema-examples.md (a real file) and signaled with a clearly labeled link, while the body stays an overview.	5 / 5
	Total	15 / 20 Passed

Description

95%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 strong: it states concrete actions, enumerates comprehensive natural trigger terms, and explicitly separates its scope from the broader seo-audit skill. Third-person voice is maintained and the 'Use when...' clause is explicit.

Dimension	Reasoning	Score
Specificity	Names the domain (schema markup/structured data) and several concrete actions ('add, fix, or optimize schema markup', 'structured data'), plus an enumerated set of schema types, but coverage of actions is moderate rather than comprehensive.	4 / 5
Completeness	Explicitly answers both 'what' ('add, fix, or optimize schema markup and structured data on their site') and 'when' ('Use when the user mentions...'), with concrete trigger phrases and a boundary pointer to seo-audit for broader issues.	5 / 5
Trigger Term Quality	Comprehensive coverage of natural trigger phrases users would say, including 'schema markup,' 'structured data,' 'JSON-LD,' 'rich snippets,' 'schema.org,' and multiple specific schema type names, with no common synonyms omitted.	5 / 5
Distinctiveness Conflict Risk	Clear niche (schema.org markup / rich results) with distinct trigger vocabulary and an explicit boundary redirect ('For broader SEO issues, see seo-audit'), minimizing overlap with adjacent SEO skills.	5 / 5
	Total	19 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: TheCraigHewitt/seomachine
Path: .claude/skills/schema-markup/SKILL.md
Commit: e818d5e

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