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
Passed
No known issues
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 conveys a specialized workflow around roadmap creation and issue decomposition with specific output artifacts, which is a strength. However, it lacks an explicit 'Use when...' clause, relies on somewhat jargon-heavy language ('iterative decomposition', 'machine-executable'), and misses natural trigger terms users would actually say when needing this skill.
Suggestions
Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks to plan a project, create a roadmap, break down requirements into tasks, or generate issues from a feature spec.'
Include common user-facing synonyms and variations such as 'project planning', 'feature breakdown', 'task decomposition', 'backlog creation', 'tickets', or 'milestones'.
Expand the 'what' with more concrete actions, e.g., 'Decomposes high-level requirements into prioritized milestones and actionable issues' rather than the abstract 'strategic requirement roadmap with iterative decomposition'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (requirement roadmapping) and some actions (iterative decomposition, issue creation), and specifies outputs (roadmap.md, issues.jsonl), but the actions are somewhat abstract—'strategic requirement roadmap' and 'iterative decomposition' are more process-oriented than concrete user-facing actions. | 2 / 3 |
Completeness | Describes what it does (creates a roadmap and issues) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and the 'what' itself is also somewhat vague, placing this at 1. | 1 / 3 |
Trigger Term Quality | Includes some relevant terms like 'roadmap', 'issues', 'decomposition', and 'requirement', but misses common natural language variations users might say such as 'plan features', 'break down tasks', 'project planning', 'backlog', 'tickets', or 'milestones'. | 2 / 3 |
Distinctiveness Conflict Risk | The specific output files (roadmap.md, issues.jsonl) and the combination of roadmapping + issue creation provide some distinctiveness, but terms like 'requirement' and 'issues' could overlap with general project management or issue-tracking skills. | 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 extremely thorough and actionable with excellent workflow clarity, clear phase sequencing, and explicit validation gates. However, it is severely over-long for a SKILL.md file — the full implementation code, templates, and schemas should be split into referenced files rather than inlined. The content would benefit enormously from being restructured as a concise overview with pointers to detailed implementation files.
Suggestions
Extract the roadmap.md template, issues.jsonl schema, and subagent API reference into separate referenced files (e.g., ROADMAP_TEMPLATE.md, ISSUES_SCHEMA.md, SUBAGENT_API.md) and link to them from the main skill.
Move the full Phase 1-4 implementation code into a separate IMPLEMENTATION.md file, keeping only a concise workflow summary with key decision points in the main SKILL.md.
Remove redundancy between 'Core Rules' and 'Best Practices' sections — merge into a single concise rules section.
Remove explanatory content Claude already knows (e.g., what JSONL format is, how flag parsing works) and trust Claude to infer standard patterns from the examples.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~500+ lines. Massive amounts of implementation detail (full JavaScript code for session init, strategy selection, decomposition, refinement loops, handoff) that could be in separate files. Explains concepts Claude already knows (what JSONL is, how to parse flags). The roadmap.md template, issues schema, and full phase implementations are all inlined when they should be referenced. Significant redundancy between Core Rules and Best Practices sections. | 1 / 3 |
Actionability | Highly actionable with complete, executable JavaScript code for every phase, concrete API calls (spawn_agent, wait_agent, close_agent), specific file paths, exact JSONL schemas, and copy-paste ready templates. The issue creation commands and query interface are fully specified with real CLI examples. | 3 / 3 |
Workflow Clarity | Excellent multi-step workflow with clear phase sequencing (Phase 1→4), explicit validation checkpoints (Phase 3 iterative refinement with max 5 rounds), error recovery table, feedback loops (approve/adjust/modify/replan), and success criteria listed after each phase. The ASCII workflow diagram provides a clear overview. Destructive operations are guarded by confirmation gates. | 3 / 3 |
Progressive Disclosure | Monolithic wall of content with no references to external files. The full roadmap.md template, complete JSONL schema, entire implementation code for all 4 phases, subagent API reference, and error handling are all inlined in a single massive document. The roadmap template, issue schema, and phase implementations should each 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 (902 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
0f8e801
- 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.