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`. Part of the skills-for-java project
77
71%
Does it follow best practices?
Impact
Pending
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
85%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 well-structured description that clearly defines both what the skill does and when to use it, with a strong 'Use when' trigger clause. Its main weakness is that the trigger terms are heavily domain-specific jargon (OpenSpec, change artifacts, proposal/spec/tasks flow), which may only match users already familiar with the terminology. The description is specific and distinctive but could benefit from slightly more natural language variations.
Suggestions
Add natural language trigger variations such as 'convert plan to specification', 'generate spec from requirements plan', or 'create change proposal from plan file' to improve discoverability for users who may not use exact OpenSpec terminology.
| 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.md files into OpenSpec change artifacts. | 3 / 3 |
Completeness | Clearly answers both 'what' (validate OpenSpec, initialize project, create/update change proposal/spec/tasks) and 'when' (explicitly starts with 'Use when you need to take a *.plan.md file and turn it into OpenSpec change artifacts'). The 'Use when' clause is explicit. | 3 / 3 |
Trigger Term Quality | Includes some relevant terms like '*.plan.md', 'OpenSpec', 'change artifacts', 'change proposal/spec/tasks', but these are fairly domain-specific jargon. Missing more natural user phrases like 'convert plan to spec' or 'generate openspec from plan'. The term 'plan.md' is a good file-pattern trigger though. | 2 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with a clear niche: converting *.plan.md files specifically into OpenSpec change artifacts within the skills-for-java project. The combination of OpenSpec, plan.md files, and the specific workflow makes it very unlikely to conflict with other skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill covers the right scope and has good structural organization with appropriate progressive disclosure to a reference file. However, it lacks an explicit step-by-step workflow with validation checkpoints and concrete examples showing actual input/output, which weakens both actionability and workflow clarity. The 'What is covered' section adds redundancy without adding value.
Suggestions
Add an explicit numbered workflow section (e.g., '## Workflow') showing the step-by-step sequence from reading the plan.md through archiving, with validation checkpoints and error recovery guidance (e.g., 'If `openspec validate --all` fails, review errors and fix before re-validating').
Include a concrete example showing a sample plan.md snippet and the corresponding OpenSpec commands/artifacts that would be generated, making the skill more actionable.
Remove or condense the 'What is covered in this Skill?' bullet list, as it largely duplicates information in the Constraints section and adds unnecessary tokens.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill includes a 'What is covered' summary section that largely duplicates the constraints and workflow steps below it, adding token overhead. The bullet list of topics is somewhat redundant with the constraints section. However, it doesn't over-explain concepts Claude already knows. | 2 / 3 |
Actionability | The skill provides specific CLI commands (e.g., `openspec --version`, `openspec init`, `openspec validate --all`, `openspec archive`) but lacks executable code blocks or concrete examples showing input/output. The constraints are specific but the actual workflow steps are described rather than demonstrated with copy-paste ready sequences. | 2 / 3 |
Workflow Clarity | The constraints imply a clear sequence (read plan → check CLI → init if needed → create/update change → validate → archive), but this sequence is never explicitly laid out as numbered steps with validation checkpoints. The validate-before-archive step is mentioned but there's no explicit error recovery loop (e.g., what to do if validation fails). For a workflow involving document manipulation and multi-step CLI operations, the lack of an explicit feedback loop caps this at 2. | 2 / 3 |
Progressive Disclosure | The skill provides a clear overview with well-organized sections (Constraints, When to use, Reference) and points to a single reference file `references/042-planning-openspec.md` for detailed guidance. This is a clean one-level-deep reference structure with clear navigation. | 3 / 3 |
Total | 9 / 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
81b047f
- 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.