sdd-propose
Create an SDD change proposal with intent, scope, and approach. Trigger: orchestrator launches proposal work for a change.
50
56%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./internal/assets/skills/sdd-propose/SKILL.mdQuality
Discovery
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 |
Implementation
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 |
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 — 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
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.