sdd-propose

Create an SDD change proposal with intent, scope, and approach. Trigger: orchestrator launches proposal work for a change.

Quality

58%

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 ./internal/assets/skills/sdd-propose/SKILL.md

Quality

Content

56%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 skill lays out a clear, well-sequenced proposal workflow with a concrete template, but it leans on external shared files that are not bundled, making the guidance non-self-contained, and it repeats mode-branch logic across multiple steps.

Suggestions

Bundle the referenced shared files (sdd-phase-common.md, openspec-convention.md) or inline the critical Sections A-D so the skill is self-contained and actionable without external dependencies.

Consolidate the per-mode IF/ELSE branches stated in the Persistence Contract and repeated in Steps 2-3 into a single mode-dispatch table to remove redundancy.

Add an explicit pre-persist validation checkpoint that confirms the proposal satisfies the size budget, rollback plan, and success criteria before Step 5.

Dimension	Reasoning	Score
Conciseness	The body is mostly procedural and directive without explaining concepts Claude already knows, but the per-mode IF/ELSE branches repeat the same mode logic across the Persistence Contract and Steps 2-3, and the Capabilities comments are verbose, so it could be tightened.	3 / 5
Actionability	It provides a concrete, fill-in proposal.md template and explicit file paths, but key execution details are delegated to external shared files (sdd-phase-common.md Sections A/B/C/D, openspec-convention.md) that are not present in the skill's bundle, leaving the guidance incomplete and not self-contained.	3 / 5
Workflow Clarity	Steps 1-6 are clearly sequenced with explicit MANDATORY markers and a defined return envelope, but there is no explicit validation checkpoint verifying mandatory rules (size budget, rollback plan, success criteria) before the mandatory persist step.	4 / 5
Progressive Disclosure	No bundle files exist (references/, scripts/, assets/ absent), so all content lives in a single SKILL.md; headers organize it well, but the only referenced files are external shared paths not part of this skill's own bundle, and content that could be split (the template, the mode logic) is inlined.	3 / 5
	Total	13 / 20 Passed

Description

60%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 cleanly states what the skill produces and includes an explicit trigger clause, but the trigger is framed in orchestrator/system terms rather than natural user language, weakening trigger-term quality and user-facing completeness.

Suggestions

Add a user-facing 'Use when...' clause with natural trigger phrases (e.g., 'Use when drafting a change proposal, scoping an SDD change, or defining intent and approach for a change').

Broaden trigger term coverage with synonyms users actually say ('proposal', 'change scope', 'intent', 'draft a change') rather than only 'orchestrator launches proposal work'.

Surface one or two more concrete actions beyond 'create proposal' to lift specificity toward comprehensive coverage.

Dimension	Reasoning	Score
Specificity	Names the concrete deliverable ('Create an SDD change proposal') and lists specific internal components ('intent, scope, and approach'), giving several specific elements with only minor coverage gaps relative to multiple distinct actions.	4 / 5
Completeness	It has a clear 'what' ('Create an SDD change proposal with intent, scope, and approach') and an explicit 'Trigger:' clause for 'when', but the 'when' is orchestrator-driven rather than user-facing and could be more explicit.	4 / 5
Trigger Term Quality	The only trigger framing ('orchestrator launches proposal work for a change') is system/orchestrator language rather than natural user phrasing; it names 'proposal' and 'change' but lacks the synonyms and variations a user would actually say.	2 / 5
Distinctiveness Conflict Risk	'SDD change proposal' with a narrow orchestrator trigger carves a clear niche with minimal conflict risk, with only minor overlap against sibling SDD artifact-producing skills (sdd-spec, sdd-design).	4 / 5
	Total	14 / 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
metadata_field	'metadata' should map string keys to string values	Warning

	Total	15 / 16 Passed

Repository: Gentleman-Programming/gentle-ai
Path: internal/assets/skills/sdd-propose/SKILL.md
Commit: 71cf25f

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