aif-roadmap

Create or update a project roadmap with major milestones. Generates the configured roadmap artifact (default .ai-factory/ROADMAP.md) — a strategic checklist of high-level goals. Use when user says "roadmap", "project plan", "milestones", or "what to build next".

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

77%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured, highly actionable workflow with strong sequencing, confirmation gates, and a verification loop. Its main weaknesses are duplicated template content that hurts conciseness and a monolithic structure with no reference files to offload detail.

Suggestions

Remove the duplicated ROADMAP.md template: keep it once in the 'ROADMAP.md Format' section and reference it from Step 1.3 instead of repeating it.

Extract the lengthy skill-context application/enforcement guidance (Step 0) into a references file (e.g. SKILL-CONTEXT.md) and link to it, reducing the monolithic body and improving progressive disclosure.

Collapse the repeated AskUserQuestion option-block patterns where the structure is identical across modes to trim tokens.

Dimension	Reasoning	Score
Conciseness	The body is direct and procedural with no preamble explaining concepts Claude already knows, but the ROADMAP.md template is duplicated (Step 1.3 and the 'ROADMAP.md Format' section) and several AskUserQuestion option blocks repeat, so it 'could be tightened' rather than being fully lean.	2 / 3
Actionability	Provides concrete default paths, executable commands ('git log --oneline -20', 'git log --oneline --all -30'), exact AskUserQuestion menus, and a copy-paste-ready ROADMAP.md template, giving fully actionable instruction-only guidance.	3 / 3
Workflow Clarity	Three clearly sequenced modes with numbered steps, user-confirmation checkpoints before writes (1.4, 3.4), evidence-based done/partial/not-started scoring in Mode 3, and an explicit skill-context enforcement verify-then-fix loop, matching the clear-sequence-with-validation anchor.	3 / 3
Progressive Disclosure	No bundle files exist (references/scripts/assets absent) and the ~305-line SKILL.md is monolithic; the duplicated full template and lengthy skill-context guidance are inline content that could be split into signaled one-level-deep reference files, fitting the 'content that should be separate is inline' anchor.	2 / 3
	Total	10 / 12 Passed

Description

92%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, concrete description that states the artifact produced and gives explicit natural-language triggers, clearly answering both what and when. Its only weakness is mild trigger overlap with the sibling planning skill via the term 'project plan'.

Suggestions

Narrow the 'project plan' trigger to reduce overlap with /aif-plan, e.g. 'strategic roadmap' or 'high-level project plan' to keep it distinct from task-level planning.

Consider adding a one-line disambiguator contrasting this skill with /aif-plan (tasks) and /aif-implement (execution) to reinforce the niche.

Dimension	Reasoning	Score
Specificity	Names three concrete actions on a specific artifact ('Create or update a project roadmap with major milestones', 'Generates the configured roadmap artifact (default .ai-factory/ROADMAP.md) — a strategic checklist of high-level goals'), matching the multiple-specific-actions anchor rather than the partial score-2 anchor.	3 / 3
Completeness	Explicitly answers both what (create/update a milestone roadmap, generate the ROADMAP.md artifact) and when ('Use when user says...'), satisfying the explicit-trigger requirement rather than capping at 2.	3 / 3
Trigger Term Quality	Provides natural phrasings a user would actually say ('roadmap', 'project plan', 'milestones', or 'what to build next'), giving good coverage including a colloquial variation, which fits the score-3 anchor.	3 / 3
Distinctiveness Conflict Risk	The high-level strategic-milestone niche is mostly distinct, but the trigger 'project plan' plausibly overlaps with the sibling /aif-plan skill, so it is 'somewhat specific but could still overlap' rather than clearly conflict-free.	2 / 3
	Total	11 / 12 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: lee-to/ai-factory
Path: skills/aif-roadmap/SKILL.md
Commit: 4b943ec

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

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.