042-planning-openspec
Use when you need to take a `*.plan.md` file and turn it into OpenSpec change artifacts by validating OpenSpec installation, initializing or reusing an OpenSpec project, and creating or updating a change proposal/spec/tasks flow. Includes a concrete workflow based on `examples/requirements-examples/problem1/requirements/openspec`. This should trigger for requests such as Convert `*.plan.md` into OpenSpec; Add change proposal from plan; Update existing OpenSpec project; Initialize OpenSpec in requirements folder. Part of cursor-rules-java project
80
75%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/042-planning-openspec/SKILL.mdQuality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong skill description that clearly defines what it does (converts plan.md files into OpenSpec change artifacts through a multi-step workflow), when to use it (explicit trigger clause with multiple natural request examples), and occupies a distinct niche. The description is well-structured with concrete actions, explicit trigger guidance, and domain-specific terminology that minimizes conflict risk.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: validating OpenSpec installation, initializing or reusing an OpenSpec project, creating or updating a change proposal/spec/tasks flow, and converting plan files into OpenSpec change artifacts. | 3 / 3 |
Completeness | Clearly answers both 'what' (turn plan.md files into OpenSpec change artifacts via validation, initialization, and proposal creation) and 'when' (explicit 'Use when' clause at the start plus 'This should trigger for' with specific request examples). | 3 / 3 |
Trigger Term Quality | Includes natural trigger terms users would say: 'Convert *.plan.md into OpenSpec', 'Add change proposal from plan', 'Update existing OpenSpec project', 'Initialize OpenSpec in requirements folder', plus file pattern '*.plan.md'. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with a clear niche: OpenSpec change artifacts from *.plan.md files, referencing specific project context (cursor-rules-java) and a concrete example path. Unlikely to conflict with other skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a reasonable high-level framework for converting plan files into OpenSpec change artifacts, with clear constraints and a sequenced workflow. However, it lacks concrete executable examples (no code blocks with actual commands and expected outputs), has redundant content sections that inflate token usage, and the workflow's most critical step (creating/updating change artifacts) is too abstract to be truly actionable.
Suggestions
Add concrete code blocks showing exact command sequences with expected outputs for each workflow step, especially step 4 (e.g., show the actual file structure and content of a proposal, design, and tasks.md file).
Add an explicit feedback loop for validation failures in step 5: what errors look like, how to diagnose them, and how to fix and re-validate before archiving.
Remove the 'What is covered in this Skill?' bullet list, which duplicates the workflow and constraints sections, to improve conciseness.
Provide a concrete end-to-end example showing a sample *.plan.md input and the resulting OpenSpec artifacts, either inline or in a referenced example file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill includes some unnecessary verbosity like the 'What is covered in this Skill?' bullet list that largely duplicates the workflow and constraints sections. The table-of-contents style summary adds tokens without adding value. However, the constraints and workflow sections are reasonably tight. | 2 / 3 |
Actionability | The skill mentions specific CLI commands (openspec --version, openspec init, openspec validate --all, openspec archive <change-id>) but never provides executable code blocks showing exact command sequences, expected outputs, or concrete examples of creating change artifacts. The workflow steps describe what to do at a high level but lack copy-paste ready commands and concrete file content examples. | 2 / 3 |
Workflow Clarity | The 5-step workflow is clearly sequenced and includes a validation step (openspec validate --all) before archiving. However, there are no explicit feedback loops for validation failures (e.g., what to do if validate fails), and the steps for creating/updating change artifacts (step 4) are vague—no specifics on what files to create or how to structure proposal/design/tasks content. | 2 / 3 |
Progressive Disclosure | The skill references 'references/042-planning-openspec.md' for detailed guidance, which is a good one-level-deep reference. However, no bundle files were provided to verify this reference exists, and the skill itself contains redundant sections (the bullet list summary, the 'When to use' section, and the workflow overlap) that could be better organized. The reference to the example path is mentioned but not linked or structured for easy navigation. | 2 / 3 |
Total | 8 / 12 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 — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- jabrena/cursor-rules-java
- Commit
ef4eba3
- 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.