guidance

Constrain LLM output with grammars; guarantee valid JSON.

Quality

53%

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 ./optional-skills/mlops/guidance/SKILL.md

Quality

Content

53%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 highly actionable with thorough executable examples and good progressive-disclosure structure pointing to real reference files, but it is notably verbose and padded with explanatory/marketing material Claude already knows, and its multi-step workflows lack explicit validation checkpoints.

Suggestions

Trim padded sections — remove "Benefits" bullet lists, the "How it works" token-healing explanation, the alternatives comparison table, and "Performance Characteristics" marketing claims — to assume Claude's competence.

Add explicit validation/verification checkpoints to the ReAct and chain-of-thought workflows (e.g. assert parsed JSON, retry on parse failure) to lift workflow clarity.

Move the duplicated "Common Patterns" detail into examples.md and keep the SKILL.md body as a concise overview with pointers, reducing inline overlap.

Dimension	Reasoning	Score
Conciseness	The ~565-line body contains several padded sections Claude does not need — per-concept "Benefits" bullet lists, "How it works" prose explaining tokenization/token healing, a comparison table, and marketing-style "Performance Characteristics" ("30-50% faster", "18,000+ stars").	2 / 5
Actionability	Abundant copy-paste-ready Python covering Quick Start, context managers, regex/select/grammar, and five common patterns; minor gaps such as the OpenAI remote-backend example and the loose string-concat grammar snippet keep it just below fully executable.	4 / 5
Workflow Clarity	Multi-step patterns (ReAct, chain-of-thought) are sequenced, but there are no explicit validation checkpoints or error-recovery feedback loops; constrained generation acts only as implicit validation.	3 / 5
Progressive Disclosure	Clear section structure with a well-signaled one-level-deep "See Also" pointing to real files (constraints.md, backends.md, examples.md, all verified present); minor gap is that the five inlined "Common Patterns" overlap content that examples.md already covers.	4 / 5
	Total	13 / 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 states what the skill does concisely but omits any "when to use" trigger guidance, leaving completeness and trigger-term quality at mid-level. Distinctiveness is reasonable thanks to the specific grammar/JSON framing.

Suggestions

Add a "Use when..." clause naming concrete triggers, e.g. "Use when generating guaranteed-valid JSON or constraining LLM output with regex/grammars."

Broaden trigger terms with user-natural synonyms like "structured output" and "constrained generation".

List a couple more concrete actions (regex constraints, select() for fixed categories) to lift specificity toward comprehensive coverage.

Dimension	Reasoning	Score
Specificity	"Constrain LLM output with grammars" and "guarantee valid JSON" name the domain plus two concrete actions, but coverage is not comprehensive — no mention of regex, select, or multi-step workflows.	3 / 5
Completeness	The "what" is clear (constrain output, guarantee JSON) but the "when" is entirely absent — there is no "Use when..." clause, which caps completeness at 3 per the rubric guidelines.	3 / 5
Trigger Term Quality	Terms like "LLM output", "grammars", and "valid JSON" are relevant but the description misses natural user phrasings such as "structured output", "constrained generation", or any "Use when..." trigger.	3 / 5
Distinctiveness Conflict Risk	Grammar-based JSON validation is a fairly distinct niche with limited overlap, but the lack of explicit trigger phrases keeps it just below the clearest-niche anchor.	4 / 5
	Total	13 / 20 Passed

Validation

75%

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

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (581 lines); consider splitting into references/ and linking	Warning
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	12 / 16 Passed

Repository: NousResearch/hermes-agent
Path: optional-skills/mlops/guidance/SKILL.md
Commit: 6680afb

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