json-output-review

Review machine-readable JSON output changes for schema stability, determinism, and downstream usability. Use when changes affect JSON output, result fields, ordering, snapshots, or integration contracts.

Quality

78%

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/json-output-review/SKILL.md

Quality

Content

72%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 maximally lean and mostly actionable, but it delegates its substance to an external file outside the bundle and leaves the review workflow's decision criteria implicit. Workflow clarity and progressive disclosure are the weak points.

Suggestions

Add one or two concrete criteria for choosing between APPROVE, CONCERN, and BLOCK (e.g. "CONCERN for added/renamed fields; BLOCK for removed fields or changed ordering") to make the verdict step executable.

Number the steps (read reviewer file → inspect snapshots/schemas → apply focus checklist → emit verdict) so the workflow sequence is explicit rather than inferred from line order.

Bring the essential review criteria into the SKILL.md (or a bundled reference file under references/) instead of relying on `.agents/agents/json-output-reviewer.md`, which is not part of the skill bundle.

Dimension	Reasoning	Score
Conciseness	Every line is instruction — a file to read, five named focus areas, and an explicit verdict protocol — with no padding and no explanation of concepts Claude already knows, matching anchor 5's lean, competence-assuming profile.	5 / 5
Actionability	Concrete guidance dominates (specific file to read, named review dimensions, the APPROVE/CONCERN/BLOCK output protocol), but "Also check any related snapshots, schema files, and output docs" is directional rather than specific, matching anchor 4 rather than anchor 5's fully copy-paste-ready coverage.	4 / 5
Workflow Clarity	The sequence is only implicit (read the reviewer file, inspect artifacts, apply focus areas, emit a verdict) and no criteria are given for choosing among APPROVE, CONCERN, or BLOCK — matching anchor 3's "sequence present but checkpoints missing or implicit" rather than anchor 4's explicit sequence with most checkpoints.	3 / 5
Progressive Disclosure	The skill's substantive detail lives in `.agents/agents/json-output-reviewer.md`, which is not part of the skill bundle, and the 16-line body has no section organization — structure exists but relies on a non-bundled reference, matching anchor 3 rather than the simple-skill exception or anchor 4's well-placed content.	3 / 5
	Total	15 / 20 Passed

Description

83%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.

A strong description that explicitly covers both what the skill does and when to use it, with domain-specific trigger terms. It is held below top marks by single-verb action coverage and minor overlap with general code-review skills.

Suggestions

Add a second concrete action verb (e.g. "Flags breaking changes and validates output contracts") to broaden the what-clause beyond a single "Review" action.

Include additional natural trigger variants such as "schema changes", "output format", or ".json files" to round out keyword coverage.

Dimension	Reasoning	Score
Specificity	Names the domain and concrete review dimensions ("schema stability, determinism, and downstream usability") but relies on a single action verb ("Review"), so it lists focus areas rather than several distinct actions — anchor 4, not anchor 5's multiple concrete actions.	4 / 5
Completeness	Explicitly answers both "what" ("Review machine-readable JSON output changes for schema stability, determinism, and downstream usability") and "when" ("Use when changes affect JSON output, result fields, ordering, snapshots, or integration contracts") with concrete trigger phrases — a clear anchor-5 match, better than anchor 4's less-specific when-clause.	5 / 5
Trigger Term Quality	"JSON output, result fields, ordering, snapshots, integration contracts" are natural terms users would say, but a few common variants are missing (e.g. "schema changes", ".json files"), matching anchor 4 rather than anchor 5's synonym/extension comprehensiveness.	4 / 5
Distinctiveness Conflict Risk	The machine-readable-output niche with triggers like "ordering, snapshots, integration contracts" is mostly distinct, but the general "review changes" framing creates minor overlap risk with code-review skills, matching anchor 4 rather than anchor 5's minimal conflict risk.	4 / 5
	Total	17 / 20 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: fallow-rs/fallow
Path: .claude/skills/json-output-review/SKILL.md
Commit: 74177e5

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