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

84%

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

73%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, actionable overview with a clear validated workflow and a properly bundled one-level reference. Its main weakness is token efficiency: the /create-spec issue-mode requirements and coverage lists are duplicated between Constraints, the Workflow, and the reference file.

Suggestions

State the /create-spec issue-mode snapshot rules once (in the reference file) and have both the Constraints bullet and Workflow step 1 cross-reference it, instead of repeating nearly identical multi-clause text in both places.

Trim or merge the 'What is covered in this Skill?' bullet list, which largely restates the Constraints and 'When to use this skill' sections.

Move detailed pagination/count-reconciliation mechanics (e.g. 'cross-check the retrieved comment count when the provider exposes a total') out of SKILL.md into references/042-planning-openspec.md, keeping only the stop-condition principle inline.

Dimension	Reasoning	Score
Conciseness	The /create-spec issue-mode rules are stated nearly verbatim in both the Constraints bullets ('exhaust every accessible comment page... stop before scope assessment or OpenSpec authoring') and Workflow step 1, and the 'What is covered in this Skill?' list restates items already covered by Constraints and 'When to use this skill'. Mostly efficient, but noticeably could be tightened through deduplication.	3 / 5
Actionability	Concrete commands are provided ('openspec --version', 'openspec new change <change-id>', 'openspec init', 'openspec validate --all') with clear conditions for each, and scaffold/placeholder-removal details are explicit. Minor gaps remain in artifact-authoring specifics, which are deferred to the reference.	4 / 5
Workflow Clarity	Six clearly sequenced steps with explicit validation checkpoints (step 5 'Validate authority and alignment', step 6 'Run openspec validate --all'), a stop-before-authoring condition in step 1, and user-approval gates for change maps and archiving, providing feedback loops for error recovery.	5 / 5
Progressive Disclosure	A single, real, well-signaled one-level-deep reference (references/042-planning-openspec.md, linked in step 1 and in a Reference section) keeps the overview navigable. However, the long inline Constraints section duplicates material that also lives in the reference, so some content that could be separate remains inline.	4 / 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.

A strong description that clearly and explicitly states both capabilities and trigger conditions in third person, with a concrete trigger list. The only weaknesses are slight: a couple of capability statements are policy-flavored rather than concrete actions, and a few natural trigger variants (archive, validate) are omitted.

Dimension	Reasoning	Score
Specificity	The description lists several specific actions ('assesses reviewable scope, records source authority and derivation, handles conflicts, and prevents silent synchronization'), but 'handles conflicts' and 'prevents silent synchronization' are policy statements rather than fully concrete operations, leaving minor gaps in coverage.	4 / 5
Completeness	It explicitly answers both what ('creating or updating OpenSpec artifacts from an issue, plan, approved design, ADRs, existing OpenSpec, or a valid combination' plus the workflow summary) and when ('Use when creating or updating...' plus a dedicated 'Triggers include' list with concrete trigger phrases), in third-person voice.	5 / 5
Trigger Term Quality	Trigger phrases like 'Create OpenSpec from an issue; Convert a plan into OpenSpec; Update an OpenSpec change; Split broad requirements into reviewable changes' are natural user phrasings with good coverage, though archive/validate variants and 'proposal'/'spec' synonyms are missing.	4 / 5
Distinctiveness Conflict Risk	'OpenSpec' names a distinct niche tool with dedicated, unambiguous triggers ('Create OpenSpec', 'Convert a plan into OpenSpec'), so the risk of triggering the wrong skill is minimal.	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: dca88dc

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