sdd-propose

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

Quality

56%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./internal/assets/skills/sdd-propose/SKILL.md

Quality

Content

77%

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

This is a well-structured, actionable skill that clearly guides Claude through creating an SDD change proposal. Its main strengths are the complete proposal template, explicit mode-conditional logic, and clear step sequencing. Its weaknesses are moderate verbosity from repeated mode branching and some inline content that could be more concise, though the overall quality is solid.

Suggestions

Consolidate the mode-conditional logic (engram/openspec/hybrid/none) into a single reference table at the top rather than repeating it in every step, reducing token count significantly.

Consider moving the full proposal.md template to a separate reference file and keeping only a brief summary of required sections inline, improving conciseness.

Dimension	Reasoning	Score
Conciseness	The skill is moderately efficient but has some verbosity. The repeated mode-conditional blocks (engram/openspec/hybrid/none) across multiple steps add bulk. The proposal template itself is well-structured but the surrounding instructions could be tighter. The orchestrator gate preamble and some explanatory comments within the template add tokens without much value for Claude.	2 / 3
Actionability	The skill provides a complete, copy-paste-ready proposal.md template with all sections filled with placeholder guidance. Each step has concrete actions with specific file paths, artifact keys, and mode-conditional behavior clearly spelled out. The return summary format is also fully specified.	3 / 3
Workflow Clarity	The 6-step workflow is clearly sequenced with explicit steps for loading skills, creating directories, reading specs, writing the proposal, persisting artifacts, and returning a summary. The persistence step is marked as MANDATORY. Mode-conditional branching is explicit at each step. The rules section adds validation constraints (size budget, capabilities section required, rollback plan required).	3 / 3
Progressive Disclosure	The skill references shared files like `skills/_shared/sdd-phase-common.md` and `skills/_shared/openspec-convention.md` for Sections A-D, which is good progressive disclosure. However, no bundle files were provided to verify these references exist, and the main skill itself is quite long (~150 lines) with the full proposal template inline. The template could arguably be a separate reference file, though having it inline is defensible for a single-document skill.	2 / 3
	Total	10 / 12 Passed

Description

35%

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 identifies a specific artifact type (SDD change proposal) and its components, which provides some clarity. However, it relies on internal system jargon ('orchestrator launches proposal work') rather than natural user language for triggers, and lacks comprehensive detail about what concrete actions the skill performs beyond creation.

Suggestions

Replace the orchestrator-specific trigger with natural language trigger terms a user might say, e.g., 'Use when the user needs to draft a change proposal, document a system design change, or define the intent and scope of a modification.'

Expand the specificity of actions beyond 'create' — describe what the skill actually does, such as 'Drafts structured change proposals including problem statement, intended changes, affected components, and implementation approach.'

Add common user-facing keywords like 'change request', 'design change', 'proposal document', 'RFC', or 'design decision' to improve trigger term coverage.

Dimension	Reasoning	Score
Specificity	Names the domain (SDD change proposal) and lists some components (intent, scope, approach), but doesn't elaborate on what concrete actions are performed beyond 'create'. It's somewhat specific but not comprehensive.	2 / 3
Completeness	The 'what' is partially addressed (create an SDD change proposal with intent, scope, and approach). The 'when' is stated but refers to an internal orchestrator trigger rather than providing explicit user-facing trigger guidance, making it weak.	2 / 3
Trigger Term Quality	The trigger terms are highly technical and internal ('orchestrator launches proposal work for a change'). A user would not naturally say these words; they reference an internal system concept rather than natural language a user would use.	1 / 3
Distinctiveness Conflict Risk	The mention of 'SDD change proposal' provides some niche specificity, but the term 'proposal' and 'change' are generic enough to potentially overlap with other proposal or change management skills. The orchestrator trigger adds some distinctiveness but only within a specific system context.	2 / 3
	Total	7 / 12 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 — 9 / 11 Passed

Validation for skill structure

Criteria	Description	Result
metadata_field	'metadata' should map string keys to string values	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	9 / 11 Passed

Repository: sergiodvillegas-art/gentle-ai
Commit: 3bfa934

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