openspec-new-change

Start a new OpenSpec change using the experimental artifact workflow. Use when the user wants to create a new feature, fix, or modification with a structured step-by-step approach.

Quality

78%

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 ./.agents/skills/openspec-new-change/SKILL.md

Quality

Content

78%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.

A tightly written, actionable CLI workflow skill with clear sequencing, an explicit stop checkpoint, and useful guardrails. The only real weakness is the absence of failure-handling feedback loops for the underlying commands.

Suggestions

Add brief error-recovery guidance for CLI failures (e.g., what to do if 'openspec new change' reports an error or missing CLI), which would lift workflow_clarity from 4 to 5.

Trim the descriptive lines after each code block (e.g., 'This creates a scaffolded change at...') since Claude can infer them from the command output.

Optionally show one concrete example of a resolved <first-artifact-id> (e.g., 'proposal' for the default schema) to close the actionability gap.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's competence (numbered steps, code blocks, no concept explanations), with only minor post-command annotations like 'This shows which artifacts need to be created...' that could be trimmed, fitting the efficient-with-minor-over-explanation anchor.	4 / 5
Actionability	Concrete, copy-paste-ready commands are provided throughout ('openspec new change "<name>"', 'openspec status --change "<name>"', 'openspec instructions <first-artifact-id> --change "<name>"'); the runtime-determined <first-artifact-id> placeholder is a minor gap versus fully-specified commands, holding it at 4.	4 / 5
Workflow Clarity	A clear six-step sequence with an explicit 'STOP and wait for user direction' checkpoint and guardrails that act as validation (invalid kebab-case name, pre-existing change); it falls short of 5 because there is no error-recovery guidance if the openspec CLI commands themselves fail.	4 / 5
Progressive Disclosure	The skill is self-contained with no external references needed and is organized into clearly signaled sections (Input, Steps, Output, Guardrails), satisfying the short-single-purpose-skill exception for well-organized content without nested or buried references.	5 / 5
	Total	17 / 20 Passed

Description

78%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.

A concise, well-formed description that clearly states both what the skill does and when to use it, with natural trigger phrases and a distinct OpenSpec niche. The main gap is limited action/synonym variety rather than any structural flaw.

Suggestions

Add one or two natural synonyms to the trigger clause (e.g., '...create a new feature, fix, enhancement, or modification') to broaden keyword coverage.

Consider naming the concrete first action beyond 'Start a new change' (e.g., scaffold the change and inspect artifact status) to lift specificity from 3 to 4.

Clarify the distinction from sibling OpenSpec skills by signaling this is specifically for *starting* a new change (versus continuing or advancing one).

Dimension	Reasoning	Score
Specificity	Names the OpenSpec-change domain and concrete actions ('Start a new OpenSpec change', 'create a new feature, fix, or modification') but lists a single workflow action rather than several specific actions, so it matches the 1-2-actions anchor rather than the multi-action anchor at 4.	3 / 5
Completeness	It explicitly answers both 'what' ('Start a new OpenSpec change using the experimental artifact workflow') and 'when' via a concrete 'Use when the user wants to create a new feature, fix, or modification' clause, matching the explicit-both-with-triggers anchor.	5 / 5
Trigger Term Quality	Natural trigger phrases users would say are present ('create a new feature, fix, or modification'), giving good keyword coverage; it stops short of score 5 because synonyms and variations like 'update', 'enhance', or 'add functionality' are missing.	4 / 5
Distinctiveness Conflict Risk	The 'OpenSpec' / 'artifact workflow' framing carves a clear niche with minimal conflict risk, but the generic 'create a new feature' trigger and likely sibling OpenSpec skills create minor overlap, landing at 4 rather than 5.	4 / 5
	Total	16 / 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: fengshao1227/ccg-workflow
Path: .agents/skills/openspec-new-change/SKILL.md
Commit: cc8cc34

Reviewed: 1 day 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.