validation-contract-check

Validate and align the repo's validation and preflight guidance with the live command contract. Use this skill when AGENTS, README, Makefile, package scripts, validators, or preflight docs change.

Quality

85%

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

Quality

Content

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

A well-organized, lean instruction skill with concrete validation commands, a clear sequenced workflow, and properly signaled one-level references. The main improvement is folding the validation gate inline into the workflow steps and making the reconcile steps more concretely executable.

Dimension	Reasoning	Score
Conciseness	The body is lean with no padding about concepts Claude already knows: short sections like "Derive truth from executable contracts first; docs are downstream artifacts" and terse Workflow bullets where every token earns its place; the only mild overhead is the table of contents, which aids navigation rather than padding.	5 / 5
Actionability	It gives executable commands ("bash scripts/verify-work.sh --fast", "bash scripts/codex-preflight.sh ...") and concrete scan patterns ("source .../scripts/codex-preflight.sh"); not a 5 because the reconcile/rewrite steps ("Derive the live contract", "Check ... for drift") are directional rather than copy-paste ready.	4 / 5
Workflow Clarity	Six numbered Workflow steps form a clear sequence and the separate Validation section provides fail-fast with a concrete gate plus a Failure mode feedback loop; not a 5 because the validation checkpoint is decoupled from the step flow rather than embedded as an explicit inline checkpoint.	4 / 5
Progressive Disclosure	Three one-level-deep references (alignment-checklist.md, contract.yaml, evals.yaml) are each real bundle files with a clear "Read when" signal, the body stays an overview, and navigation is easy — matching the top anchor.	5 / 5
	Total	18 / 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, third-person description that cleanly states what the skill does and when to use it with concrete artifact-based triggers. Minor gains are possible by adding more action verbs and a few synonym/extension trigger terms.

Dimension	Reasoning	Score
Specificity	"Validate and align the repo's validation and preflight guidance with the live command contract" names the domain and two concrete actions, plus enumerates the specific contract surfaces (AGENTS, README, Makefile, package scripts, validators, preflight docs); not a 5 because the action verbs are only validate/align rather than a comprehensive list.	4 / 5
Completeness	It explicitly answers both what ("Validate and align the repo's validation and preflight guidance with the live command contract") and when ("Use this skill when ... docs change") with concrete trigger phrases, matching the top anchor.	5 / 5
Trigger Term Quality	The "Use this skill when AGENTS, README, Makefile, package scripts, validators, or preflight docs change" clause gives good natural-term coverage of artifacts a user would mention; not a 5 because it lacks synonyms or extensions like .json/.mk and phrasing variants.	4 / 5
Distinctiveness Conflict Risk	The validation-contract-alignment niche with named artifacts (AGENTS, Makefile, codex-preflight) is mostly distinct with minor overlap risk against generic code-review/doc-maintenance skills; not a 5 because "validation and preflight guidance" could lightly overlap with sibling QA skills.	4 / 5
	Total	17 / 20 Passed

Validation

81%

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

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning
relative_links	Relative link issues: 1 suspicious	Warning
referenced_paths_exist	Referenced path issues: 8 missing	Warning

	Total	13 / 16 Passed

Repository: jscraik/diagram-cli
Path: .codex/skills/validation-contract-check/SKILL.md
Commit: a07a18d

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