042-planning-openspec

Use when creating or updating OpenSpec artifacts from an issue, plan, approved design, ADRs, existing OpenSpec, or a valid combination. The workflow assesses reviewable scope, records source authority and derivation, handles conflicts, and prevents silent synchronization. Triggers include Create OpenSpec from an issue; Convert a plan into OpenSpec; Update an OpenSpec change; Split broad requirements into reviewable changes. Part of Plinth Toolkit

Quality

79%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/042-planning-openspec/SKILL.md

Quality

Content

71%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 overview with concrete OpenSpec commands, clear sequenced workflow steps, and proper progressive disclosure to one reference file. The chief weakness is conciseness: the issue-mode constraints and Step 1 overlap substantially and could be deduplicated.

Suggestions

De-duplicate the /create-spec issue-mode handling: state it once (in Step 1) and have the Constraints section reference it rather than restating paginated-comment and snapshot retrieval rules verbatim.

Add an explicit validate-fail feedback loop in Step 6 (e.g., 'if openspec validate --all fails, fix the reported artifacts and re-run until it passes before archiving').

Trim or group redundant MUST bullets (e.g., combine the source-recording and derivation-direction constraints) to tighten token use.

Dimension	Reasoning	Score
Conciseness	Mostly efficient and assumes Claude knows OpenSpec, but the long MUST/MUST NOT constraint list re-states issue-mode handling that is repeated almost verbatim in Step 1, adding padding that could be tightened.	3 / 5
Actionability	Provides concrete commands ('openspec --version', 'openspec init', 'openspec new change <change-id>', 'openspec validate --all') and named artifacts with only minor gaps in exact flags; mostly executable guidance.	4 / 5
Workflow Clarity	A clear 6-step sequence with explicit validation checkpoints ('openspec validate --all', user-approval archive gate) and stop-guards, but the validate-fail-then-retry feedback loop is not spelled out, keeping it below 5.	4 / 5
Progressive Disclosure	SKILL.md is a concise overview with a single clearly signaled one-level-deep reference to references/042-planning-openspec.md (a real bundle file), matching the top anchor for clean navigation.	5 / 5
	Total	16 / 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.

The description is strong: it answers both what and when with concrete, third-person trigger language and occupies a distinct niche. The main weakness is mild abstractness and domain jargon in the capability phrasing, which keeps specificity and trigger quality just below the top level.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('assesses reviewable scope, records source authority and derivation, handles conflicts, and prevents silent synchronization') plus named artifact types, with only minor coverage gaps; framed slightly abstractly so not a 5.	4 / 5
Completeness	Explicitly answers both what it does and when to use it ('Use when creating or updating OpenSpec artifacts...') with concrete trigger phrases, matching the top anchor.	5 / 5
Trigger Term Quality	Includes natural user-facing phrasing ('creating or updating OpenSpec artifacts from an issue, plan, approved design, ADRs') and explicit 'Triggers include Create OpenSpec from an issue; Convert a plan into OpenSpec'; good coverage but somewhat domain-jargon heavy, so below 5.	4 / 5
Distinctiveness Conflict Risk	Targets a clear niche (OpenSpec change planning) with distinct triggers and specific artifact types, giving minimal conflict risk with other skills.	5 / 5
	Total	18 / 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: jabrena/plinth
Path: skills/042-planning-openspec/SKILL.md
Commit: 05bf9d1

Reviewed: 6 minutes 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.