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

86%

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

81%Weight 40%Scale 1-5

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

The body delivers an unusually actionable, well-sequenced workflow with explicit validation and confirmation gates, concrete prompts, and exact commands. Its main weakness is token efficiency: the roadmap template is duplicated verbatim and the skill-context precedence rules are over-explained, and a 310-line single file leaves some room for better content splitting.

Suggestions

Remove the duplicated ROADMAP.md template — keep it only in the 'ROADMAP.md Format' section and reference it from Mode 1 step 1.3, cutting ~20 lines.

Compress the skill-context block (lines 42-60) to the essentials: it is MANDATORY, skill-context rules override general rules, and violations must be fixed before presenting output — the repeated rationale can be trimmed to one sentence.

Consider moving the full Mode 2/Mode 3 substep detail into a reference file (e.g., references/modes.md) so SKILL.md stays a lean overview of the three modes, improving progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient operational detail, but it is padded in places: the ROADMAP.md template appears twice in full (Mode 1 step 1.3 and the "ROADMAP.md Format" section), and the skill-context block spans ~19 lines repeatedly re-explaining its precedence rationale ("same principle as nested CLAUDE.md files", "they exist because the project's experience proved the default insufficient"). This matches anchor 3 — could be meaningfully tightened — better than anchor 4's 'minor instances'.	3 / 5
Actionability	Guidance is fully executable for an instruction-only skill: exact interactive prompts with numbered options ("AskUserQuestion: What are the major goals for this project?"), exact commands ("git log --oneline -20", "git log --oneline --all -30"), concrete tool usage (Glob for structure, Grep for features), a copy-paste-ready ROADMAP.md template, and explicit evidence-scoring criteria (done/partial/not started). Specific examples cover the common cases, matching anchor 5.	5 / 5
Workflow Clarity	The sequence is explicit and well-gated: Step 0 loads context, Step 1 determines mode, and each mode has numbered substeps with validation checkpoints — user confirmation before saving (step 1.4), before marking milestones complete (step 3.4), the rule "Never remove milestones silently", and an enforcement feedback loop ("After generating any output artifact, verify it against all skill-context rules. If any rule is violated — fix the output before presenting it"). This matches anchor 5's clear sequence with explicit validation and error-recovery loops.	5 / 5
Progressive Disclosure	No bundle files (references/, scripts/, assets/) exist, so all content is inline in a single ~310-line SKILL.md. Section structure is good and navigation is easy, but the file carries three full mode workflows plus a duplicated format template that could be split out, leaving minor organization gaps — anchor 4 rather than anchor 5's clean overview with well-signaled one-level-deep references.	4 / 5
	Total	17 / 20 Passed

Description

91%Weight 40%Scale 1-5

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 description: it uses third person, states concrete actions with a default artifact path, and provides an explicit 'Use when' clause with natural trigger terms including an informal synonym. The only weaknesses are the unmentioned check-progress capability and the "project plan" trigger's overlap with the sibling /aif-plan skill.

Dimension	Reasoning	Score
Specificity	The description lists several concrete actions — "Create or update a project roadmap with major milestones" and "Generates the configured roadmap artifact (default .ai-factory/ROADMAP.md)" — including a concrete artifact path, but coverage has minor gaps (e.g., the check-progress mode and the completed-milestone tracking are not mentioned). It exceeds the 1-2 actions of anchor 3 but falls short of the comprehensive coverage of anchor 5.	4 / 5
Completeness	It explicitly answers both questions: what ("Create or update a project roadmap with major milestones. Generates the configured roadmap artifact") and when ("Use when user says 'roadmap', 'project plan', 'milestones', or 'what to build next'") with concrete trigger phrases. This matches the anchor-5 example structure exactly; anchor 4 would require a less explicit 'when' clause.	5 / 5
Trigger Term Quality	The trigger list "roadmap", "project plan", "milestones", or "what to build next" covers the natural synonyms a user would say, including the informal phrasing "what to build next". Coverage is comprehensive for this domain, matching anchor 5; no common user phrasing is obviously missing.	5 / 5
Distinctiveness Conflict Risk	The roadmap/milestone niche is clear and mostly distinct, but the trigger "project plan" overlaps the closely related sibling skill /aif-plan, which the body itself distinguishes only by granularity ("high-level goal, not a granular task (that's /aif-plan)"). That is minor overlap risk with a closely related skill, matching anchor 4 rather than the minimal-conflict anchor 5.	4 / 5
	Total	18 / 20 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: ac92beb

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.