openspec-propose

Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.

1.04x

Quality

72%

Does it follow best practices?

Impact

69%

1.04x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.github/skills/openspec-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 provides clear step-by-step guidance for proposing changes with artifact generation. Its main strengths are concrete CLI commands, explicit validation checkpoints, and good workflow sequencing. Minor weaknesses include some redundancy in the 'don't copy context/rules' instruction and the content being slightly verbose in places where it could be more concise.

Suggestions

Consolidate the duplicated guidance about not copying context/rules into artifacts—state it once clearly in the guidelines section and remove from step 4a.

Tighten the introductory lines and step descriptions to reduce token count without losing clarity (e.g., the bullet list at the top repeating what's in the steps).

Dimension	Reasoning	Score
Conciseness	The skill is mostly efficient but has some redundancy—e.g., the repeated emphasis on not copying context/rules into output files (stated in both step 4a and the guidelines section), and some explanatory text that could be tightened. However, it largely avoids explaining concepts Claude already knows.	2 / 3
Actionability	The skill provides concrete, executable commands (openspec new change, openspec status, openspec instructions), specific tool references (AskUserQuestion, TodoWrite), clear JSON field names to parse, and explicit output format. Steps are copy-paste ready with real CLI invocations.	3 / 3
Workflow Clarity	The multi-step process is clearly sequenced with explicit validation checkpoints: checking status after each artifact creation, verifying artifact files exist before proceeding, re-running status to confirm applyRequires completion, and a feedback loop for unclear context. Error recovery paths are specified (ask user, check if change exists).	3 / 3
Progressive Disclosure	The content is reasonably well-structured with clear sections (Input, Steps, Output, Guidelines, Guardrails), but everything is in a single file with no references to supporting documentation. The artifact creation guidelines and guardrails sections could potentially be split out, though for a skill of this length (~90 lines) it's borderline acceptable.	2 / 3
	Total	10 / 12 Passed

Description

67%

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 has a clear structure with both 'what' and 'when' clauses, which is its strongest aspect. However, it suffers from somewhat vague capability descriptions—'design, specs, and tasks' are broad terms that don't convey exactly what artifacts are produced. The trigger terms are adequate but could be more comprehensive to cover natural user phrasings.

Suggestions

Be more specific about the artifacts generated—e.g., 'Generates a design document, technical specification, and implementation task list' instead of 'design, specs, and tasks'.

Add more natural trigger terms users might say, such as 'plan a feature', 'RFC', 'project kickoff', 'scaffold a project', or 'new feature proposal'.

Dimension	Reasoning	Score
Specificity	It names some actions ('propose a new change', 'generate artifacts') and mentions outputs like 'design, specs, and tasks', but these are somewhat vague—what kind of design? What specs? It doesn't list multiple concrete, distinct actions.	2 / 3
Completeness	It clearly answers both 'what' (propose a new change with all artifacts in one step) and 'when' (when the user wants to quickly describe what they want to build and get a complete proposal). The 'Use when' clause is explicit.	3 / 3
Trigger Term Quality	Includes some relevant terms like 'proposal', 'design', 'specs', 'tasks', and 'build', but misses common user phrasings like 'plan', 'project', 'feature request', 'RFC', 'kickoff', or 'scaffold'. The terms are somewhat generic.	2 / 3
Distinctiveness Conflict Risk	Terms like 'design', 'specs', and 'tasks' could overlap with skills focused on design documents, specification writing, or task management individually. The distinguishing factor is the 'all in one step' aspect, but it's not strongly differentiated.	2 / 3
	Total	9 / 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: arm/mlia
Commit: 3e21e30

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