instructor

Extract structured data from LLM responses with Pydantic validation, retry failed extractions automatically, parse complex JSON with type safety, and stream partial results with Instructor - battle-tested structured output library

Quality

73%

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 ./backend/cli/skills/llm-tools/instructor/SKILL.md

Quality

Content

75%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 comprehensive executable examples and decent structure, but it carries marketing fluff and some redundancy that hurt token efficiency, and the long inline reference material could be pushed deeper into the existing bundle files.

Suggestions

Remove the marketing stats line and the 'Comparison to Alternatives' table, or move them to a reference file; they cost tokens without improving execution.

Consolidate the repeated near-identical client.messages.create calls into one parameterized snippet rather than restating max_tokens/messages for every example.

Add an explicit validate-then-retry checkpoint to the batch processing pattern, which currently has no validation step.

Dimension	Reasoning	Score
Conciseness	Mostly efficient code-centric content, but padded with a marketing line ('GitHub Stars: 15,000+ \| Battle-tested: 100,000+ developers'), a comparison table, and several near-identical client.messages.create examples that could be tightened or offloaded.	3 / 5
Actionability	Abundant copy-paste-ready, executable Python covering extraction, validation, retries, streaming, providers, and common patterns — concrete and complete for the common cases.	5 / 5
Workflow Clarity	The retry feedback loop is explicitly sequenced ('How it works' 1-5) and error handling is shown with try/except, though there is no end-to-end usage checklist and the batch pattern lacks a validation checkpoint.	4 / 5
Progressive Disclosure	Well-organized sections with a 'See Also' block pointing to real one-level-deep references (validation.md, providers.md, examples.md), though the SKILL.md itself is large and could offload more detail to those files.	4 / 5
	Total	16 / 20 Passed

Description

71%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 on specificity and distinctiveness, with concrete actions and a clear library identity, but it omits any 'when to use this' trigger guidance, which caps completeness and weakens discoverability.

Suggestions

Append an explicit trigger clause, e.g. 'Use when extracting structured/typed data from LLM responses, validating LLM output against a schema, or streaming partial structured results.'

Add a couple of natural synonyms users might say ('schema', 'type-safe responses', 'JSON into objects') to broaden trigger coverage.

Drop the marketing qualifier 'battle-tested structured output library' — it is fluff that does not aid triggering.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Extract structured data', 'Pydantic validation', 'retry failed extractions automatically', 'parse complex JSON with type safety', 'stream partial results' — giving comprehensive coverage of the library's capabilities.	5 / 5
Completeness	Has a clear 'what' (extract/validate/retry/parse/stream) but no 'Use when...' clause or equivalent trigger guidance, so per the rubric completeness is capped at 3.	3 / 5
Trigger Term Quality	Good natural keyword coverage ('structured data', 'LLM responses', 'Pydantic validation', 'JSON', 'stream partial results'), but a few natural terms users might say (e.g. 'schema', 'type-safe responses') are missing, so it stops short of comprehensive.	4 / 5
Distinctiveness Conflict Risk	The named 'Instructor' library with Pydantic-validation framing carves a mostly distinct niche, though broad terms like 'JSON parsing' and 'validation' create minor overlap risk with adjacent skills.	4 / 5
	Total	16 / 20 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (742 lines); consider splitting into references/ and linking	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: synthetic-sciences/openscience
Path: backend/cli/skills/llm-tools/instructor/SKILL.md
Commit: fcd2e11

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