roadmap-with-file
Strategic requirement roadmap with iterative decomposition and issue creation. Outputs roadmap.md (human-readable, single source) + issues.jsonl (machine-executable).
53
43%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./.codex/skills/roadmap-with-file/SKILL.mdQuality
Discovery
32%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 communicates the core output artifacts well (roadmap.md and issues.jsonl) and hints at a structured decomposition process, but it reads more like a technical summary than a skill selection guide. It lacks explicit trigger guidance ('Use when...') and natural user-facing keywords, making it difficult for Claude to reliably select this skill from a large pool. The language is also somewhat jargon-heavy without grounding in concrete user scenarios.
Suggestions
Add an explicit 'Use when...' clause with natural trigger phrases, e.g., 'Use when the user asks to plan a project, break down requirements into tasks, create a feature roadmap, or generate issues from a specification.'
Include more natural user keywords such as 'project planning', 'feature breakdown', 'create tickets', 'backlog', 'milestones', 'epic decomposition', or 'task planning'.
Expand the 'what' with more concrete actions, e.g., 'Decomposes high-level requirements into structured milestones and actionable issues, generates a human-readable roadmap (roadmap.md) and machine-executable issue list (issues.jsonl).'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (requirement roadmapping) and some actions (iterative decomposition, issue creation) with specific outputs (roadmap.md, issues.jsonl), but the actions themselves are somewhat abstract—'strategic requirement roadmap' and 'iterative decomposition' are more process descriptions than concrete user-facing actions. | 2 / 3 |
Completeness | Describes what it does (creates roadmaps and issues via decomposition) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, missing 'Use when' caps completeness at 2, and the 'what' is also only partially clear, warranting a 1. | 1 / 3 |
Trigger Term Quality | Includes some relevant terms like 'roadmap', 'issues', and 'decomposition', but misses many natural user phrases like 'plan features', 'break down requirements', 'create tickets', 'project planning', 'backlog', or 'milestones'. The terms used lean more technical/process-oriented than what users would naturally say. | 2 / 3 |
Distinctiveness Conflict Risk | The specific output files (roadmap.md, issues.jsonl) and the combination of roadmapping + issue creation provide some distinctiveness, but 'requirement' and 'roadmap' could overlap with general project planning or issue tracking skills. The niche is somewhat defined but not sharply delineated. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
55%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is highly actionable and has excellent workflow clarity with clear phase sequencing, validation gates, and error handling. However, it is severely over-engineered for a single SKILL.md file — the ~500+ lines include redundant sections, full templates, complete implementation code, and API references that should be split into separate bundle files. The verbosity significantly undermines its effectiveness as a context-window-efficient skill.
Suggestions
Extract the roadmap.md template, JSONL schema, and subagent API reference into separate bundle files (e.g., TEMPLATE.md, SCHEMA.md, API.md) and reference them from the main skill
Remove redundant sections — 'Core Rules' and 'Best Practices' overlap significantly; 'Usage Recommendations' comparing other skills is unnecessary context
Trim implementation code blocks to show only the critical decision logic (e.g., uncertainty assessment, mode selection) and omit boilerplate like mkdir, string formatting, and template initialization that Claude can generate
Consolidate the output structure explanation — the 'Output Artifacts', 'Why No Separate JSON Files', and 'Output Structure' sections all describe the same thing from different angles
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~500+ lines. Massive amounts of implementation detail that Claude could infer, redundant sections (Core Rules repeats Best Practices), full template scaffolding with placeholder comments, and extensive inline code that could be summarized. The roadmap.md template, JSONL schema, and implementation sections all contain significant padding. | 1 / 3 |
Actionability | Highly actionable with executable JavaScript code for every phase, concrete CLI commands, specific API calls (spawn_agent, wait_agent, close_agent), complete JSONL schemas, and copy-paste ready templates. Every step has concrete implementation guidance. | 3 / 3 |
Workflow Clarity | Excellent multi-phase workflow with clear sequencing (Phase 1→4 + Terminal Gate), explicit validation checkpoints (success criteria per phase, MANDATORY terminal gate), feedback loops in Phase 3 with max-round limits, and comprehensive error handling table with specific resolutions for each failure mode. | 3 / 3 |
Progressive Disclosure | Monolithic wall of text with no bundle files to offload content to. The full roadmap.md template, JSONL schema, implementation details for all 4 phases, subagent API reference, and query interface are all inlined. Content like the template, schema, and API reference should be in separate referenced files. | 1 / 3 |
Total | 8 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (907 lines); consider splitting into references/ and linking | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Repository
- catlog22/Claude-Code-Workflow
- Commit
227244f
- 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.