skill-recommender（技能推荐员）

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

Skill Workflow

Step 1: Parse User Intent

Extract action verbs and targets from the user request:

Intent Categories:

Target Extraction:

Step 2: Match Skills

Match parsed intent against skill catalog:

Skill Catalog (Core Documentation Skills):

Quality Assurance Skills:

Utility Skills:

Planning Skills:

Step 3: Score and Rank

Calculate confidence scores based on:

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

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

Traceability

Required Tags:

@prd: PRD.000.001
@adr: ADR-000

Upstream Sources

Downstream Artifacts

Version Information

Version: 1.0.0 Created: 2025-11-29 Status: Active Author: AI Dev Flow Framework Team