instructor

Structured LLM outputs validated with Pydantic.

Quality

55%

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/instructor/SKILL.md

Quality

Content

57%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, but it is severely over-long, padded with explanations of known concepts and repeated boilerplate, and inlines material that belongs in the existing reference files. Tightening the body and routing detail to the references would markedly improve conciseness and progressive disclosure.

Suggestions

Trim explanations of known concepts (Pydantic benefits, what response models are) and remove the marketing line; let code stand on its own.

Factor the repeated model/max_tokens boilerplate out (e.g. define once, reference) and avoid hardcoding the date-stamped model version in every snippet.

Move provider configuration, advanced features, and the comparison table into the existing references and link to them inline at the relevant sections instead of inlining everything.

Dimension	Reasoning	Score
Conciseness	The ~730-line body is noticeably verbose: it explains concepts Claude already knows (e.g. 'Response models define the structure and validation rules', Pydantic benefit lists), repeats model/max_tokens boilerplate across ~15 snippets, includes marketing fluff ('15,000+ stars', '100,000+ developers'), and hardcodes a time-sensitive model version repeatedly.	2 / 5
Actionability	Provides fully executable, copy-paste-ready Python covering the common cases (extraction, validation, streaming, retries, multi-provider, error handling) with concrete, complete code.	5 / 5
Workflow Clarity	Sequences exist (the retry 'How it works' steps, error handling) but the Batch Processing pattern has no validation checkpoint, and the rubric caps workflow clarity at 3 for batch/destructive operations lacking validation.	3 / 5
Progressive Disclosure	Real references exist (validation.md, providers.md, examples.md) and are listed in 'See Also', but the bulk of provider config, advanced features, and API-style examples are inlined in a ~730-line body with references barely signaled inline rather than at the relevant sections.	3 / 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 is concise and names a specific, distinctive niche, but it omits any 'Use when...' trigger guidance and only states a single concrete action. Adding explicit trigger phrases and one or two more actions would lift the lower-scoring dimensions.

Suggestions

Add a 'Use when...' clause with concrete triggers, e.g. 'Use when extracting structured data, validating LLM output against a schema, or parsing JSON with retries'.

Mention 1-2 more concrete actions (e.g. 'retries failed validations automatically', 'streams partial results') to raise specificity.

Include natural synonyms users say ('JSON parsing', 'data extraction', 'schema validation') to improve trigger-term coverage.

Dimension	Reasoning	Score
Specificity	Names the domain ('Structured LLM outputs') and one concrete action ('validated with Pydantic'), but lists only a single action rather than comprehensive coverage.	3 / 5
Completeness	Provides a clear 'what' but no 'when' / 'Use when...' trigger clause, which caps completeness at 3 per the rubric guideline.	3 / 5
Trigger Term Quality	Includes relevant terms ('Structured LLM outputs', 'Pydantic', 'validated') but misses common synonyms and natural phrasing like 'JSON', 'data extraction', or 'schema'.	3 / 5
Distinctiveness Conflict Risk	The Pydantic-validated structured-output framing is a clear niche with only minor overlap risk against generic JSON/schema skills, though it lacks an explicit distinguishing trigger phrase.	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 (745 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/instructor/SKILL.md
Commit: 6680afb

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