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

65%

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

A highly actionable skill with extensive executable code, but it is over-long, padded with marketing fluff and conceptual explanation, and duplicates content that already lives in its reference files. Workflow guidance for batch operations lacks validation checkpoints.

Suggestions

Remove marketing claims and redundant conceptual explanations (e.g. 'GitHub Stars', 'Benefits:' lists, 'How it works' retry narrative) and consolidate overlapping Quick Start / Core Concepts / Common Patterns examples.

Defer provider configuration and validation detail to references/providers.md and references/validation.md instead of duplicating them inline, keeping SKILL.md a concise overview.

Add an explicit validate/verify checkpoint to the batch-processing pattern (Pattern 5) so failed extractions are caught before continuing.

Dimension	Reasoning	Score
Conciseness	The ~730-line body includes marketing fluff ('GitHub Stars: 15,000+ \| Battle-tested: 100,000+ developers') and conceptual explanations Claude already knows ('Pydantic validates LLM outputs automatically', 'Benefits:' lists, the 'How it works' retry narrative), plus heavy redundancy across Quick Start, Core Concepts, Common Patterns, and Advanced Features; it is mostly efficient but could be tightened, so not a 1 or a 3.	2 / 3
Actionability	Provides abundant executable, copy-paste-ready code across extraction, validation, streaming, and provider config with specific examples, matching the score-3 anchor for fully executable, specific guidance.	3 / 3
Workflow Clarity	The skill is largely a feature catalog rather than a sequenced workflow, and the batch-processing pattern (Pattern 5) lacks any validation/verification checkpoint, which per the guidelines caps workflow clarity at 2; the retry feedback loop is described but not framed as an explicit checkpointed sequence.	2 / 3
Progressive Disclosure	The See Also references (validation.md, providers.md, examples.md) are real and one level deep, but provider configuration and validation content is duplicated inline rather than delegated to those reference files, fitting the score-2 anchor where content that should be separate is inline.	2 / 3
	Total	9 / 12 Passed

Description

82%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A specific, well-scoped description that names concrete actions and natural trigger terms and is clearly distinct. Its main weakness is the absence of an explicit 'Use when...' trigger clause, which caps completeness.

Suggestions

Add an explicit 'Use when...' clause naming concrete triggers, e.g. 'Use when extracting structured/JSON data from LLM responses, validating outputs with Pydantic, or streaming partial results.'

Drop the marketing tag '- battle-tested structured output library' to remove fluff and tighten the description.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Extract structured data', 'retry failed extractions automatically', 'parse complex JSON with type safety', 'stream partial results' — matching the score-3 anchor for listing several specific concrete actions.	3 / 3
Completeness	It clearly states what the skill does but contains no 'Use when...' clause or equivalent explicit trigger guidance, so per the judging guidelines completeness is capped at 2; it is not a 1 because the 'what' is strong and multi-faceted.	2 / 3
Trigger Term Quality	Includes natural terms users would actually say — 'structured data', 'LLM responses', 'Pydantic', 'JSON', 'type safety', 'structured output' — giving good coverage; not just technical jargon.	3 / 3
Distinctiveness Conflict Risk	The named library (Instructor) plus Pydantic/structured-output niche gives a clear, distinct trigger set unlikely to collide with other skills; it is not a 2 because the framing is specific rather than generic.	3 / 3
	Total	11 / 12 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: 52845c3

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