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.

Quality

82%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

81%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 body is a well-structured, highly actionable workflow with concrete CLI commands and strong validation checkpoints. Its main weakness is verbosity from redundant restatements and over-explained edge cases that assume too little of Claude.

Suggestions

Deduplicate the planning-boundary guidance: state it once in the Guardrails section and reference it from the intro rather than repeating near-verbatim three times.

Condense step 5b's edge-case prose (requires-edge closure, skip_specs, conditional artifacts) into a compact checklist; the CLI's status/instructions JSON already conveys most of this.

Consider moving the store-selection mechanics into a short reference file so the main steps stay focused on the core propose workflow.

Dimension	Reasoning	Score
Conciseness	Mostly efficient with concrete commands throughout, but the planning-boundary point is repeated in the intro, Output, and Guardrails, and step 5b over-explains edge cases (requires edges, skip_specs, conditional artifacts) that a competent Claude could infer from the CLI's JSON output.	3 / 5
Actionability	Provides fully executable, copy-paste-ready CLI commands (openspec new change, status, instructions, schemas, context) with the specific JSON fields to parse and act on, covering the common cases.	5 / 5
Workflow Clarity	A clear 6-step sequence with explicit, repeated validation checkpoints (re-run status --json, verify file existence, build the required set transitively from requires edges) and feedback loops (clarify then continue; skip then reconsider).	5 / 5
Progressive Disclosure	Well-organized into clearly signaled sections with no nested or buried references, but as a single ~137-line file with dense inline edge-case handling, some content (store-selection mechanics, step 5b detail) could be externalized rather than kept inline.	4 / 5
	Total	17 / 20 Passed

Description

83%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 is strong: it explicitly states both what it does and when to use it, names concrete output artifacts, and uses third-person imperative voice. The main gaps are slightly high-level action verbs and a few missing natural trigger synonyms.

Dimension	Reasoning	Score
Specificity	Names the domain and lists several concrete artifacts (proposal, design, specs, tasks), though the action verbs themselves are high-level ('propose', 'generate') rather than a broad set of distinct actions.	4 / 5
Completeness	Clearly answers both what ('Propose a new change with all artifacts generated in one step... design, specs, and tasks') and when via an explicit 'Use when the user wants to quickly describe what they want to build' trigger.	5 / 5
Trigger Term Quality	Good keyword coverage with natural phrases like 'describe what they want to build' and 'complete proposal', but missing common synonyms a user might say ('spec out', 'plan a feature', 'design doc').	4 / 5
Distinctiveness Conflict Risk	Has a clear, specific niche (OpenSpec change proposal with planning artifacts) and distinct triggers, with only minor overlap risk against the sibling openspec-apply workflow that also mentions 'change'.	4 / 5
	Total	17 / 20 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: Fission-AI/OpenSpec
Path: skills/openspec-propose/SKILL.md
Commit: 6926ccb

Reviewed: about 16 hours 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.