CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

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

Well-structured, lean content with a sequenced workflow, explicit fail-fast validation, a defined error-recovery loop, and correctly scoped one-level-deep references with 'Read when' signals. The only improvements are trimming redundant framing sections and making the drift-scan and summary-output steps as concrete as the validation commands.

DimensionReasoningScore

Conciseness

The body is lean bullet-style guidance with no explanations of concepts Claude already knows. Minor trimming opportunities remain: an 11-item Table of Contents on a 94-line document, an Overview that restates the description, and a Philosophy section that overlaps Constraints and Safety — matching 'efficient; minor instances that could be trimmed' rather than the every-token-earns-its-place level.

4 / 5

Actionability

Guidance is mostly executable: exact commands ('bash scripts/verify-work.sh --fast', 'bash scripts/codex-preflight.sh ...') and exact patterns to scan for ('source .../scripts/codex-preflight.sh', '. .../scripts/codex-preflight.sh'). Minor gaps: the drift scan and the 'machine-readable summary' deliverable are described but not given as runnable commands or a concrete output example, so it stops short of fully copy-paste-ready coverage.

4 / 5

Workflow Clarity

A clear 6-step sequence is paired with an explicit fail-fast validation checkpoint ('stop at the first failed gate and fix it before continuing', 'bash scripts/verify-work.sh --fast') and a Failure mode section that defines the error-recovery loop (treat docs as unverified, fix or revert the contract claim before handoff). This matches the anchor with explicit validation steps and feedback loops.

5 / 5

Progressive Disclosure

SKILL.md is a compact overview and all detail lives in three real one-level-deep bundle files (references/alignment-checklist.md, references/contract.yaml, references/evals.yaml — verified present, none nesting further), each signaled with an explicit 'Read when' condition. The one cross-skill routing link (../ci-check-name-parity/SKILL.md) sits outside this bundle but is clearly labeled as routing for a specific case.

5 / 5

Total

18

/

20

Passed

Description

82%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: third-person, concise, with an explicit 'Use this skill when' trigger clause naming concrete files and doc types. The only soft spot is capability breadth — just two verbs ('validate', 'align') — which keeps specificity at mid-scale.

DimensionReasoningScore

Specificity

The description names the domain ('validation and preflight guidance', 'live command contract') and two concrete actions ('Validate and align'), matching the anchor for domain plus 1-2 actions without comprehensive coverage. It does not list several distinct actions (e.g., detecting drift, reconciling conflicting examples), so the level-4 anchor does not fit.

3 / 5

Completeness

It explicitly answers both parts: what it does ('Validate and align the repo's validation and preflight guidance with the live command contract') and when to use it ('Use this skill when AGENTS, README, Makefile, package scripts, validators, or preflight docs change') with concrete trigger phrases. Voice is third person, so no penalty applies.

5 / 5

Trigger Term Quality

Natural trigger terms are well covered: 'AGENTS, README, Makefile, package scripts, validators, or preflight docs change' matches phrases a user would say when editing those files. A few natural terms are missing (e.g., 'quality gates', 'verify-work', specific script names), so it falls short of comprehensive synonym/extension coverage.

4 / 5

Distinctiveness Conflict Risk

It occupies a clear niche — reconciling repo validation/preflight documentation with the live command contract — with distinct, file-based triggers (AGENTS, README, Makefile, package scripts), giving minimal overlap risk with unrelated skills. It is more narrowly pinned than the level-4 anchor's 'minor overlap risk with closely related skills'.

5 / 5

Total

17

/

20

Passed

Validation

81%

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

CriteriaDescriptionResult

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

Reviewed

Table of Contents

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.