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
64
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 articulates what the skill does (converts plan.md files into OpenSpec change artifacts through a multi-step workflow), when to use it (with explicit trigger phrases), and occupies a distinct niche. The description uses proper third-person voice and includes both a 'Use when' clause and explicit trigger examples, making it highly actionable for skill selection.
| 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 change 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 specific file patterns. 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.
The skill provides a reasonable framework for converting plan files into OpenSpec artifacts with clear constraints and a sequenced workflow. Its main weaknesses are the lack of concrete, executable examples (no sample file contents, no expected command outputs) and a validation feedback loop that is stated as a requirement but not explicitly structured as a retry loop. The content is moderately concise but has redundancy between the summary bullets and the workflow/constraints sections.
Suggestions
Add a concrete example showing a sample *.plan.md input snippet and the resulting OpenSpec artifact files (proposal.md, tasks.md with checklist format) to improve actionability.
Make the validation step an explicit feedback loop: 'Run openspec validate --all → if errors, review output, fix issues, re-validate → only when passing, proceed to archive.'
Remove the 'What is covered in this Skill?' bullet list, as it duplicates information already conveyed by the Constraints and Workflow sections, improving conciseness.
| 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 provides specific CLI commands (openspec --version, openspec init, openspec validate --all, openspec archive <change-id>) but lacks executable examples showing actual file content, expected outputs, or concrete proposal/spec/tasks file structures. The workflow steps describe what to do at a high level but don't show copy-paste ready artifacts or command sequences with expected results. | 2 / 3 |
Workflow Clarity | The 5-step workflow is clearly sequenced with a validation step (openspec validate --all) before archiving, and there are edge case handling instructions. However, the validation feedback loop is implicit rather than explicit—there's no 'if validation fails, fix X and re-validate' step, and the workflow lacks concrete checkpoints between steps 3 and 4 (e.g., confirming project detection before proceeding to artifact creation). | 2 / 3 |
Progressive Disclosure | The skill references 'references/042-planning-openspec.md' for detailed guidance and mentions an example path, which is good structure. However, no bundle files were provided to verify these references exist, and the inline content includes a redundant summary section that could be offloaded. The single reference at the bottom is well-signaled but the skill could better organize what's inline vs. referenced. | 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
3fa5789
- 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.