skill-recommender Purpose
Analyze user requests and recommend appropriate documentation skills from the AI Dev Flow framework catalog.
Problem Solved: Users must know which of 25+ skills to invoke for their documentation task, requiring deep framework knowledge.
Solution: Parse user intent, match against skill catalog, and provide ranked recommendations with confidence scores and rationale.
When to Use This Skill
Use skill-recommender when:
User is unsure which skill to use for a documentation task Starting a new documentation workflow and need guidance Want to discover available skills for a specific intent Need help navigating the skill catalog
Do NOT use when:
User explicitly requests a specific skill (e.g., "/skill doc-prd") Performing non-documentation tasks User is experienced and knows the target skill Skill Inputs Input Type Required Description user_request string Yes Natural language description of what user wants to do project_context object No Project structure and existing artifacts (from context-analyzer) max_recommendations number No Maximum recommendations to return (default: 3) Skill Workflow Step 1: Parse User Intent
Extract action verbs and targets from the user request:
Intent Categories:
Category Signal Keywords Example Request create create, write, draft, new, add "Create a new PRD for user authentication" update update, modify, edit, change, revise "Update the traceability section of SPEC-01" validate validate, check, verify, audit, review "Check if my artifacts have proper traceability" analyze analyze, review, examine, inspect "Analyze the project documentation structure" plan plan, roadmap, schedule, organize "Create an implementation roadmap from ADRs"
Target Extraction:
Target Signal Keywords Maps To business requirements business, brd, objectives doc-brd product requirements product, prd, features, user stories doc-prd formal requirements ears, formal, when-the-shall doc-ears test scenarios bdd, tests, scenarios, gherkin doc-bdd architecture decisions adr, architecture, decision doc-adr system requirements sys, system, technical doc-sys requirements req, requirement, atomic doc-req implementation plan impl, implementation, plan doc-impl contracts ctr, contract, api, interface doc-ctr specifications spec, specification, yaml doc-spec tasks tasks, todo, implementation tasks doc-tasks traceability trace, traceability, links trace-check validation validate, quality, compliance doc-validator diagrams diagram, mermaid, chart, flow charts-flow, mermaid-gen roadmap roadmap, adr implementation adr-roadmap project management mvp, mmp, release, planning project-mngt Step 2: Match Skills
Match parsed intent against skill catalog:
Skill Catalog (Core Documentation Skills):
Skill ID Category Layer Description doc-brd core-workflow 1 Business Requirements Documents doc-prd core-workflow 2 Product Requirements Documents doc-ears core-workflow 3 EARS Formal Requirements doc-bdd core-workflow 4 BDD Test Scenarios doc-adr core-workflow 5 Architecture Decision Records doc-sys core-workflow 6 System Requirements doc-req core-workflow 7 Atomic Requirements doc-impl core-workflow 8 Implementation Plans (optional) doc-ctr core-workflow 9 API Contracts (optional) doc-spec core-workflow 10 Technical Specifications doc-tasks core-workflow 11 Implementation Tasks
Quality Assurance Skills:
Skill ID Category Description trace-check quality-assurance Validate bidirectional traceability doc-validator quality-assurance Validate documentation standards code-review quality-assurance Code quality review contract-tester quality-assurance Test API contracts
Utility Skills:
Skill ID Category Description charts-flow utility Mermaid architecture diagrams mermaid-gen utility Generate Mermaid diagrams analytics-flow utility Analytics and data analysis project-init utility Initialize project structure
Planning Skills:
Skill ID Category Description adr-roadmap planning ADR implementation roadmaps project-mngt planning MVP/MMP/MMR release planning doc-flow planning SDD workflow orchestration Step 3: Score and Rank
Calculate confidence scores based on:
Factor Weight Description Intent match 40% How well request matches skill intent signals Target match 30% Explicit skill/artifact type mentioned Context fit 20% Project state and workflow position Usage patterns 10% Common skill sequences
Confidence Levels:
High (≥80%): Strong match, recommend with confidence Medium (50-79%): Good match, include alternative options Low (<50%): Weak match, suggest clarification Step 4: Generate Recommendations
Format recommendations with rationale:
Output Format:
recommendations: - skill: doc-prd confidence: 92% rationale: "Request mentions 'product requirements' and 'features' - direct match for PRD creation" next_steps: "Run /skill doc-prd to create Product Requirements Document"
-
skill: doc-brd confidence: 65% rationale: "May need BRD first if business requirements not yet documented" condition: "Use if no BRD exists for this feature"
-
skill: doc-ears confidence: 45% rationale: "EARS follows PRD in workflow - consider after PRD completion" condition: "Use after PRD is complete"
clarification_needed: false clarification_question: null
Example Usage Example 1: Clear Intent
User Request: "I need to create a product requirements document for a new authentication feature"
Skill Analysis:
Intent: create (keywords: create, need) Target: product requirements (keywords: product requirements document) Domain: authentication feature
Recommendations:
recommendations: - skill: doc-prd confidence: 95% rationale: "Explicit request for Product Requirements Document" next_steps: "Run /skill doc-prd to create PRD for authentication feature"
- skill: doc-brd confidence: 40% rationale: "BRD may be needed upstream if not already created" condition: "Check if BRD exists for authentication feature"
Example 2: Ambiguous Intent
User Request: "Help me document the system architecture"
Skill Analysis:
Intent: create (keywords: document) Target: ambiguous - could be ADR, SYS, or diagrams
Recommendations:
recommendations: - skill: doc-adr confidence: 60% rationale: "Architecture decisions typically documented in ADRs"
-
skill: doc-sys confidence: 55% rationale: "System requirements capture technical architecture"
-
skill: charts-flow confidence: 50% rationale: "Architecture diagrams visualize system structure"
clarification_needed: true clarification_question: "What aspect of architecture? (1) Decisions/rationale (ADR), (2) System specs (SYS), (3) Visual diagrams?"
Example 3: Validation Request
User Request: "Check if my documentation has proper links between artifacts"
Skill Analysis:
Intent: validate (keywords: check) Target: traceability (keywords: links between artifacts)
Recommendations:
recommendations: - skill: trace-check confidence: 98% rationale: "Direct request for traceability validation" next_steps: "Run /skill trace-check to validate bidirectional links"
Integration with Other Skills Integration Description context-analyzer Receives project context for better recommendations doc-flow Can be invoked by doc-flow for skill discovery workflow-optimizer Shares workflow position awareness Quality Gates Definition of Done User request parsed successfully At least one skill recommendation provided Confidence scores calculated for all recommendations Rationale included for each recommendation Clarification question generated when ambiguous Performance Targets Metric Target Response latency <500ms Recommendation accuracy ≥85% User acceptance rate ≥70% Traceability
Required Tags:
@prd: PRD.000.001 @adr: ADR-000
Upstream Sources Source Type Reference PRD-00 Product Requirements PRD-00 ADR-000 Architecture Decision ADR-000 Downstream Artifacts Artifact Type Reference Selected doc-* skill Skill Execution Invoked based on recommendation Version Information
Version: 1.0.0 Created: 2025-11-29 Status: Active Author: AI Dev Flow Framework Team