roadmap-generator

I spent some time with your roadmap-generator and it's genuinely impressive how you've handled the token efficiency—hitting 93 points on our rubric tells me you really thought about the PDA layer. One thing I'm curious about: how do you handle the balance between giving users enough context to build meaningful roadmaps versus keeping the prompt overhead minimal?

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 93/100, firmly in A-grade territory. This is based on Anthropic's best practices for skill design. Your strongest area is Utility (19/20)—the framework actually solves a real problem. Weakest spot is Spec Compliance (12/15), which is mostly about adding a couple more trigger phrases to help people discover it.

What's Working Well

• Excellent utility design: You've built something genuinely useful—the Epic/Story/Task hierarchy with T-shirt sizing is the kind of framework teams actually use. The three-phase approach (detailed → epic-level → theme-level) respects how real planning works.

• Smart modular structure: Splitting the main skill from estimation-guide.md and generator.py shows you understand PDA. The layering works—SKILL.md gives the overview, references go one level deep. That's the sweet spot.

• Validation gates throughout: The phase checkpoints with exit criteria and estimation checklists show you've thought about feedback loops. That's not something most skills nail—you've got the run→check→fix pattern dialed in.

• Consistent terminology: Using Epic/Story/Task consistently plus the XS-XXL sizing scale makes the whole thing feel cohesive. No confusing language switching.

The Big One: Missing Navigation for Long Files

Both SKILL.md (295 lines) and estimation-guide.md (302 lines) lack a table of contents. That's a medium-severity PDA issue because readers have to scroll through to find sections.

Why it matters: When someone's looking for "how do I estimate Phase 2?" they shouldn't have to scroll 200 lines. A TOC takes 30 seconds to add and immediately improves discoverability.

Fix: Add this after the frontmatter in both files:

## Table of Contents
- [When to Use](#when-to-use)
- [Roadmap Structure](#roadmap-structure)
- [Epic/Story/Task Hierarchy](#epicstorytask-hierarchy)
- [Effort Estimation](#effort-estimation-framework)
- [Validation Checkpoints](#validation-checkpoints)
- [Output Format](#output-format)

Impact: +2 points toward PDA.

Other Things Worth Fixing

1. Add 2-3 more trigger phrases in your description. You've got "when cto-architect needs to create actionable technical roadmaps" but people search for "create project roadmap", "estimate engineering timeline", "break down features into phases". +1 point spec compliance.

2. Condense the anti-patterns section (lines 260-277). Right now it's verbose prose. Tighten it to a bulleted list: Big Bang → "Plan Phase 1 in detail, Phase 2 at epic level, Phase 3 at theme level." Saves tokens. +1 point writing style.

3. Stop repeating the T-shirt sizing table. It's in SKILL.md (lines 69-76) AND estimation-guide.md (lines 20-27). Keep the full table only in estimation-guide.md, link to it from SKILL.md. +1 point PDA.

4. Add a worked example: Templates exist but show a complete before/after—requirements doc → generated roadmap. Would push utility to 20/20.

Quick Wins

1. Add TOC to both long files (+2 points)
2. Add 2-3 discovery trigger phrases (+1 point)
3. De-duplicate the sizing table (+1 point)
4. Tighten anti-patterns prose (+1 point)

These four changes alone would push you to 96+. The skill's already solid—these are just the polish layer.

Checkout your skill here: SkillzWave.ai | SpillWave We have an agentic skill installer that install skills in 14+ coding agent platforms. Check out this guide on how to improve your agentic skills.