skill-intent-contract

Use when starting a complex or ambiguous task that risks scope drift

Quality

42%

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 ./skills/skill-intent-contract/SKILL.md

Quality

Content

48%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 lays out a genuinely clear workflow with strong end-stage validation, but it is padded with triplicated templates and benefit-listing fluff, and its executable guidance is undercut by undefined template variables and references to scripts that are not shipped in the bundle. It reads as a well-designed process document that needs a tight editorial pass and either the missing scripts or their removal.

Suggestions

Cut the duplicate contract renderings: keep the Step 2 heredoc as the single source of truth and shrink the structure template and worked example to the deltas, or move the example to a reference file.

Define or eliminate the placeholder shell variables (${USER_GOAL}, ${MIN_SUCCESS_CRITERIA}, etc.) — either inline the AskUserQuestion responses that populate them or instruct Claude to fill them from the captured answers.

Ship the referenced scripts (plan-storage.sh, routing.sh) in the bundle or replace the references with self-contained instructions so the workflow is executable as delivered; delete the 'Benefits' section and 'Ready to use!' closer.

Dimension	Reasoning	Score
Conciseness	The full intent-contract template is rendered three times (the structure template, the Step 2 heredoc, and the complete worked example), and the 'Benefits' section plus 'Ready to use!' closing add marketing padding Claude doesn't need. This is 'noticeably verbose; several unnecessary explanations or padded sections' — the duplication is systematic rather than a single instance, so it cannot reach 3.	2 / 5
Actionability	There is concrete guidance — an executable AskUserQuestion block and a bash heredoc for writing session-intent.md — but key details are missing: the heredoc depends on undefined variables (${USER_GOAL}, ${MIN_SUCCESS_CRITERIA}, ${BOUNDARIES}) with no instruction on where they come from, and every referenced script (scripts/plan-storage.sh, scripts/lib/routing.sh) is absent from the bundle. This lands at 'concrete guidance but incomplete... missing key details' rather than mostly-executable.	3 / 5
Workflow Clarity	Steps 0–5 are clearly sequenced with explicit validation checkpoints: the Step 4 validation process checks each criterion (met / not met / partially met), checks boundaries, generates a structured report, and loops back to ask the user about gaps; Step 5 defines status transitions. It falls short of 5 because 'the 3 clarifying questions' the workflow depends on are referenced but never specified, and execution depends on unavailable scripts.	4 / 5
Progressive Disclosure	Section headers organize the body well, but the content is effectively monolithic: the full contract template is inlined twice where a single reference file would serve, and all file pointers (plan-storage.sh, routing.sh, skills/blocks/codex-host-adapter.md) reference paths that do not exist in this bundle, so navigation dead-ends. This matches 'some structure... content that should be separate is inline' rather than good structure with clear, working references.	3 / 5
	Total	12 / 20 Passed

Description

36%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 a well-formed trigger clause but answers only 'when' — it never states what the skill does (capture intent contracts, define success criteria, validate outputs against intent). Without any capability statement, a user or model cannot distinguish it from general planning/scoping skills, and model invocation would rely on guessing from the trigger alone.

Suggestions

Add a 'what' clause stating the skill's concrete actions, e.g. 'Creates a persistent intent contract capturing goals, success criteria, and boundaries, and validates final output against it.'

Broaden trigger coverage with natural synonyms such as 'scope creep', 'vague requirements', or 'unclear goals' so users' actual phrasing matches.

Differentiate from general planning skills by naming the deliverable ('intent contract' / 'session-intent.md') in the description.

Dimension	Reasoning	Score
Specificity	The description names the domain ('complex or ambiguous task that risks scope drift') but lists no capabilities or actions whatsoever — it is a pure trigger clause. This fits the anchor 'names the domain but actions are minimal or generic', and is above anchor 1 only because 'scope drift' is concrete language rather than pure abstraction.	2 / 5
Completeness	Only the 'when' is present ('Use when starting a complex or ambiguous task that risks scope drift') with no statement of what the skill actually does. This exactly matches the anchor 'only when is present without what'; it cannot reach 3 because a clear 'what' is entirely absent.	2 / 5
Trigger Term Quality	'Complex', 'ambiguous', and 'scope drift' are phrases a user might naturally say, giving some relevant keywords. However common variations and synonyms are missing — e.g. 'scope creep', 'vague requirements', 'unfocused' — which keeps it at 'some relevant keywords but missing common variations' rather than good coverage.	3 / 5
Distinctiveness Conflict Risk	'Complex or ambiguous task' is broad and would overlap with planning, requirements-gathering, and scoping skills, but 'risks scope drift' narrows the niche somewhat. It sits at 'somewhat specific but could still overlap with similar skills', short of anchor 4 because the trigger condition alone doesn't clearly separate it from general planning skills.	3 / 5
	Total	10 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
referenced_paths_exist	Referenced path issues: 2 missing, 1 deeper-than-1-level	Warning

	Total	15 / 16 Passed

Repository: nyldn/claude-octopus
Path: skills/skill-intent-contract/SKILL.md
Commit: 0093dab

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.