CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

openspec-update-change

Update an OpenSpec change by revising its existing planning artifacts and keeping them coherent with one another. Use when the user wants to revise a change's plan, fold new decisions into it, or reconcile its artifacts after an edit. Also use when the user says "openspec update change" or "opsx update". If the user means the openspec update CLI command, which refreshes generated files, run that command instead. Never edits code.

69

Quality

87%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

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.

A well-engineered workflow body: fully executable commands, explicit JSON contract details, validation checkpoints and confirmation gates at every risky boundary, and clear guidance-only next-step routing. Its one weakness is token efficiency — the glob-artifact rules are restated across four sections and step 4's nested subprocedure is dense enough to tighten or split out.

Suggestions

State the glob-artifact rules once (e.g., as a dedicated subsection or a short reference file) and have step 2, step 4, Guardrails, and Output reference that single statement instead of each restating them — this would remove the largest source of repeated tokens.

Tighten step 4's five-item subprocedure: merge items 4 and 5 (both re-verify immediately before creation) into a single re-check list, and compress item 3 ("include in step 5's revisions, create after confirm") since step 5 already mandates confirmation for every write.

Trim overlapping restatements of the ready/blocked-vs-skipped routing: it appears in step 4, step 6, Output, and Guardrails; one canonical statement plus a pointer would preserve clarity at lower token cost.

DimensionReasoningScore

Conciseness

The body assumes Claude's competence — no concept explanations, just procedure — but it is noticeably repetitive: the glob-artifact rules appear in step 2, again as step 4's dense five-item subprocedure, again in Guardrails ("never write to a glob `resolvedOutputPath`… Do not advance the build frontier"), and again in Output. This fits anchor 3 ("mostly efficient but… could be tightened") better than anchor 4: the repetition goes beyond minor over-explanation.

3 / 5

Actionability

Fully executable guidance: concrete commands (`openspec status --change "<name>" --json`, `openspec instructions "<artifact-id>" --change "<name>" --json`, `openspec list --json`, `openspec store list --json`), the exact JSON fields to read (`root`, `existingOutputPaths`, `lastModified`, `isPlanningComplete`), copy-ready announce strings ("Using change: <name>"), and fail-if-exists create semantics. Not below 5: for an instruction-only skill this is copy-paste-ready procedural guidance covering the common cases.

5 / 5

Workflow Clarity

Six clearly sequenced steps with explicit validation checkpoints and feedback loops: a root check before any write, non-zero-exit-as-data guidance ("read the JSON instead of retrying"), user confirmation before every write, refresh-and-recheck immediately before creating a glob file, and stop-and-reconcile behavior when a check fails. This matches the anchor-5 example of a sequence with explicit validation and error-recovery loops.

5 / 5

Progressive Disclosure

No bundle files exist (no references/, scripts/, or assets/), and the body needs none — it is organized into well-labeled sections (Store selection, Project check, Input, Steps, Output, Guardrails) with cross-skill pointers rather than nested file references. Not 5: the five-item glob-artifact subprocedure inside step 4 inlines dense conditional detail that could be lifted into its own subsection or a reference file, which is a minor organization gap matching anchor 4.

4 / 5

Total

17

/

20

Passed

Description

87%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 strong description: it states concrete capabilities in third person, gives explicit 'use when' triggers including the literal slash-command forms, scopes itself with 'Never edits code', and pre-routes the nearest conflicting intent (the openspec update CLI). Minor room to broaden natural trigger synonyms and enumerate a wider set of distinct actions.

DimensionReasoningScore

Specificity

The description lists several concrete, domain-anchored actions ("revising its existing planning artifacts and keeping them coherent", "fold new decisions into it", "reconcile its artifacts after an edit") plus an explicit boundary ("Never edits code"). It sits between anchors 4 and 5: the actions are overlapping variations of one core operation rather than a comprehensive set of distinct capabilities, so anchor 4 ("several specific actions; minor gaps") is the closest fit, not 5's comprehensive coverage.

4 / 5

Completeness

It explicitly answers both questions: what ("Update an OpenSpec change by revising its existing planning artifacts and keeping them coherent with one another… Never edits code") and when ("Use when the user wants to revise a change's plan, fold new decisions into it, or reconcile its artifacts after an edit. Also use when the user says 'openspec update change' or 'opsx update'"). This matches the anchor-5 pattern of concrete what + explicit trigger phrases; anchor 4 would require the when to be less explicit or specific.

5 / 5

Trigger Term Quality

It includes literal phrases a user would naturally say — "openspec update change", "opsx update", "revise a change's plan", "reconcile its artifacts" — giving good keyword coverage. Not 5 because a few natural synonyms are absent (e.g., "edit the plan", "update the spec", "make the plan consistent"); not 3 because the terms present are specific and varied rather than generic.

4 / 5

Distinctiveness Conflict Risk

The niche is clear (updating an OpenSpec change's planning artifacts) and the description actively defuses the one real collision — the `openspec update` CLI command — with explicit routing ("If the user means the openspec update CLI command… run that command instead"). Third-person voice is used throughout, so no voice penalty applies; conflict risk with sibling OpenSpec skills is minimal.

5 / 5

Total

18

/

20

Passed

Validation

100%

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-update-change/SKILL.md

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.