skill-intent-contract

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

Quality

36%

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

Quality

Content

50%

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

The skill body delivers a clear, actionable intent-contract workflow with concrete code and a validation step, but it is verbose through template duplication and offers no progressive disclosure via separate files. The bash heredoc's unexplained placeholders and the /octo:* command references slightly undermine executability and consistency.

Suggestions

De-duplicate the intent contract template: keep one canonical template and reference it from the bash heredoc and the worked example instead of repeating it three times.

Replace the ${VAR} placeholders in the bash heredoc with concrete substitution instructions or a fully executable script, and resolve the /octo:* slash-command references to the Codex host equivalents mentioned in the header note.

Move the full worked example and the integration-with-workflows detail into a separate reference file (e.g. EXAMPLES.md) referenced one level deep, so SKILL.md stays a lean overview.

Dimension	Reasoning	Score
Conciseness	The body is mostly useful but padded: the intent contract template appears essentially three times (structure, bash heredoc, full worked example) and a 'Benefits' section restates obvious value, fitting 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than lean.	2 / 3
Actionability	It provides copy-paste-ready AskUserQuestion code and a validation report template, but the bash heredoc relies on unexplained ${VAR} placeholders that are not executable as written, matching 'some concrete guidance but incomplete; pseudocode...missing key details'.	2 / 3
Workflow Clarity	The five-step sequence is clearly laid out with an explicit validation step and checklist, but the validation checkpoint is soft (no automated re-check) and the steps reference /octo:* slash commands that the host note says are unavailable, leaving checkpoints partly implicit and inconsistent.	2 / 3
Progressive Disclosure	No bundle files exist and the content is a single monolithic file with templates and a full example that could be split out; it is well-sectioned but inlines material that would be better separated, matching 'some structure but content that should be separate is inline'.	2 / 3
	Total	8 / 12 Passed

Description

22%

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 supplies an explicit trigger but omits any statement of what the skill actually does, leaving it incomplete and only vaguely specific. It is distinguishable from some skills via 'scope drift' but still risks overlapping with generic planning skills.

Suggestions

Add a concrete capability statement describing what the skill does, e.g. 'Creates a persistent intent contract that captures goals, success criteria, and boundaries, then validates final outputs against them.'

Expand the trigger with natural variations users would actually say, such as 'when the task is unclear, when requirements might drift, or when you need to lock down scope before a multi-phase workflow'.

Tie the trigger to a more distinctive hook (e.g. 'before starting a multi-phase workflow') to reduce overlap with general planning skills.

Dimension	Reasoning	Score
Specificity	The description states only a trigger context ("complex or ambiguous task that risks scope drift") and names no concrete actions the skill performs, matching the 'vague or no actions' anchor rather than the level-2 anchor that requires naming some actions.	1 / 3
Completeness	It gives the 'when' ("Use when starting a complex or ambiguous task...") but never states what the skill does, so it is missing half of the required what/when pair, which the level-1 anchor covers for a missing component.	1 / 3
Trigger Term Quality	It opens with a natural 'Use when' and includes a recognizable phrase ('scope drift'), but terms like 'complex or ambiguous task' are generic and it lacks common variations, fitting the 'some relevant keywords but missing common variations' anchor rather than full coverage.	2 / 3
Distinctiveness Conflict Risk	'scope drift' hints at a niche but 'complex or ambiguous task' is broad and would overlap with general planning/scoping skills, matching the 'somewhat specific but could still overlap' anchor rather than a clearly distinct niche.	2 / 3
	Total	6 / 12 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: nyldn/claude-octopus
Path: .claude/skills/skill-intent-contract/SKILL.md
Commit: 9f39f0c

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