Back to Details

skill-recommender

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
分析用户请求，从AI Dev Flow框架目录中推荐合适的文档技能。
解决的问题：用户必须了解25+种技能中哪一种适用于他们的文档任务，这需要具备深厚的框架知识。
解决方案：解析用户意图，与技能目录匹配，并提供带有置信度分数和理由的排序推荐。

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-recommender:
  • 用户不确定哪种技能适用于文档任务
  • 启动新的文档工作流并需要指导
  • 想要发现针对特定意图的可用技能
  • 需要帮助浏览技能目录
请勿在以下场景使用:
  • 用户明确请求特定技能（例如："/skill doc-prd"）
  • 执行非文档类任务
  • 用户经验丰富且知晓目标技能

Skill Inputs

技能输入项

InputTypeRequiredDescription
user_requeststringYesNatural language description of what user wants to do
project_contextobjectNoProject structure and existing artifacts (from context-analyzer)
max_recommendationsnumberNoMaximum recommendations to return (default: 3)
输入项类型是否必填描述
user_requeststring是用户想要执行操作的自然语言描述
project_contextobject否项目结构和现有工件（来自context-analyzer）
max_recommendationsnumber否返回的最大推荐数（默认值：3）

Skill Workflow

技能工作流

Step 1: Parse User Intent

步骤1：解析用户意图

Extract action verbs and targets from the user request:
Intent Categories:
CategorySignal KeywordsExample 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:
TargetSignal KeywordsMaps To
business requirementsbusiness, brd, objectivesdoc-brd
product requirementsproduct, prd, features, user storiesdoc-prd
formal requirementsears, formal, when-the-shalldoc-ears
test scenariosbdd, tests, scenarios, gherkindoc-bdd
architecture decisionsadr, architecture, decisiondoc-adr
system requirementssys, system, technicaldoc-sys
requirementsreq, requirement, atomicdoc-req
implementation planimpl, implementation, plandoc-impl
contractsctr, contract, api, interfacedoc-ctr
specificationsspec, specification, yamldoc-spec
taskstasks, todo, implementation tasksdoc-tasks
traceabilitytrace, traceability, linkstrace-check
validationvalidate, quality, compliancedoc-validator
diagramsdiagram, mermaid, chart, flowcharts-flow, mermaid-gen
roadmaproadmap, adr implementationadr-roadmap
project managementmvp, mmp, release, planningproject-mngt
从用户请求中提取动作动词和目标对象：
意图类别:
类别标识关键词示例请求
create
create, write, draft, new, add"为用户认证创建一份新的PRD"
update
update, modify, edit, change, revise"更新SPEC-01的可追溯性章节"
validate
validate, check, verify, audit, review"检查我的工件是否具备正确的可追溯性"
analyze
analyze, review, examine, inspect"分析项目文档结构"
plan
plan, roadmap, schedule, organize"从ADRs创建一份实施路线图"
目标对象提取:
目标对象标识关键词对应技能
业务需求business, brd, objectivesdoc-brd
产品需求product, prd, features, user storiesdoc-prd
正式需求ears, formal, when-the-shalldoc-ears
测试场景bdd, tests, scenarios, gherkindoc-bdd
架构决策adr, architecture, decisiondoc-adr
系统需求sys, system, technicaldoc-sys
需求req, requirement, atomicdoc-req
实施计划impl, implementation, plandoc-impl
契约ctr, contract, api, interfacedoc-ctr
技术规格spec, specification, yamldoc-spec
任务tasks, todo, implementation tasksdoc-tasks
可追溯性trace, traceability, linkstrace-check
验证validate, quality, compliancedoc-validator
图表diagram, mermaid, chart, flowcharts-flow, mermaid-gen
路线图roadmap, adr implementationadr-roadmap
项目管理mvp, mmp, release, planningproject-mngt

Step 2: Match Skills

步骤2：匹配技能

Match parsed intent against skill catalog:
Skill Catalog (Core Documentation Skills):
Skill IDCategoryLayerDescription
doc-brdcore-workflow1Business Requirements Documents
doc-prdcore-workflow2Product Requirements Documents
doc-earscore-workflow3EARS Formal Requirements
doc-bddcore-workflow4BDD Test Scenarios
doc-adrcore-workflow5Architecture Decision Records
doc-syscore-workflow6System Requirements
doc-reqcore-workflow7Atomic Requirements
doc-implcore-workflow8Implementation Plans (optional)
doc-ctrcore-workflow9API Contracts (optional)
doc-speccore-workflow10Technical Specifications
doc-taskscore-workflow11Implementation Tasks
Quality Assurance Skills:
Skill IDCategoryDescription
trace-checkquality-assuranceValidate bidirectional traceability
doc-validatorquality-assuranceValidate documentation standards
code-reviewquality-assuranceCode quality review
contract-testerquality-assuranceTest API contracts
Utility Skills:
Skill IDCategoryDescription
charts-flowutilityMermaid architecture diagrams
mermaid-genutilityGenerate Mermaid diagrams
analytics-flowutilityAnalytics and data analysis
project-initutilityInitialize project structure
Planning Skills:
Skill IDCategoryDescription
adr-roadmapplanningADR implementation roadmaps
project-mngtplanningMVP/MMP/MMR release planning
doc-flowplanningSDD workflow orchestration
将解析后的意图与技能目录匹配：
技能目录（核心文档技能）:
技能ID类别层级描述
doc-brdcore-workflow1业务需求文档
doc-prdcore-workflow2产品需求文档
doc-earscore-workflow3EARS正式需求
doc-bddcore-workflow4BDD测试场景
doc-adrcore-workflow5架构决策记录
doc-syscore-workflow6系统需求
doc-reqcore-workflow7原子需求
doc-implcore-workflow8实施计划（可选）
doc-ctrcore-workflow9API契约（可选）
doc-speccore-workflow10技术规格
doc-taskscore-workflow11实施任务
质量保证技能:
技能ID类别描述
trace-checkquality-assurance验证双向可追溯性
doc-validatorquality-assurance验证文档标准
code-reviewquality-assurance代码质量评审
contract-testerquality-assurance测试API契约
实用技能:
技能ID类别描述
charts-flowutilityMermaid架构图表
mermaid-genutility生成Mermaid图表
analytics-flowutility分析与数据分析
project-initutility初始化项目结构
规划技能:
技能ID类别描述
adr-roadmapplanningADR实施路线图
project-mngtplanningMVP/MMP/MMR发布规划
doc-flowplanningSDD工作流编排

Step 3: Score and Rank

步骤3：评分与排序

Calculate confidence scores based on:
FactorWeightDescription
Intent match40%How well request matches skill intent signals
Target match30%Explicit skill/artifact type mentioned
Context fit20%Project state and workflow position
Usage patterns10%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
基于以下因素计算置信度分数：
因素权重描述
意图匹配度40%请求与技能意图标识的匹配程度
目标匹配度30%是否明确提及技能/工件类型
上下文适配度20%项目状态和工作流阶段
使用模式10%常见技能使用序列
置信度等级:
  • 高（≥80%）：匹配度高，可放心推荐
  • 中（50-79%）：匹配度良好，需包含备选选项
  • 低（<50%）：匹配度弱，建议用户澄清需求

Step 4: Generate Recommendations

步骤4：生成推荐

Format recommendations with rationale:
Output Format:
yaml
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
为推荐结果添加理由并格式化：
输出格式:
yaml
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

示例1：意图明确的请求

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:
yaml
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"
用户请求："我需要为新的认证功能创建一份产品需求文档"
技能分析:
Intent: create (keywords: create, need)
Target: product requirements (keywords: product requirements document)
Domain: authentication feature
推荐结果:
yaml
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

示例2：意图模糊的请求

User Request: "Help me document the system architecture"
Skill Analysis:
Intent: create (keywords: document)
Target: ambiguous - could be ADR, SYS, or diagrams
Recommendations:
yaml
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?"
用户请求："帮我记录系统架构"
技能分析:
Intent: create (keywords: document)
Target: ambiguous - could be ADR, SYS, or diagrams
推荐结果:
yaml
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

示例3：验证类请求

User Request: "Check if my documentation has proper links between artifacts"
Skill Analysis:
Intent: validate (keywords: check)
Target: traceability (keywords: links between artifacts)
Recommendations:
yaml
recommendations:
  - skill: trace-check
    confidence: 98%
    rationale: "Direct request for traceability validation"
    next_steps: "Run /skill trace-check to validate bidirectional links"
用户请求："检查我的文档工件之间是否有正确的关联链接"
技能分析:
Intent: validate (keywords: check)
Target: traceability (keywords: links between artifacts)
推荐结果:
yaml
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

与其他技能的集成

IntegrationDescription
context-analyzerReceives project context for better recommendations
doc-flowCan be invoked by doc-flow for skill discovery
workflow-optimizerShares workflow position awareness
集成对象描述
context-analyzer接收项目上下文以优化推荐结果
doc-flow可被doc-flow调用以实现技能发现
workflow-optimizer共享工作流阶段感知能力

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

性能指标

MetricTarget
Response latency<500ms
Recommendation accuracy≥85%
User acceptance rate≥70%
指标目标值
响应延迟<500ms
推荐准确率≥85%
用户接受率≥70%

Traceability

可追溯性

Required Tags:
@prd: PRD.000.001
@adr: ADR-000
必填标签:
@prd: PRD.000.001
@adr: ADR-000

Upstream Sources

上游来源

SourceTypeReference
PRD-00Product RequirementsPRD-00
ADR-000Architecture DecisionADR-000
来源类型参考链接
PRD-00产品需求PRD-00
ADR-000架构决策ADR-000

Downstream Artifacts

下游工件

ArtifactTypeReference
Selected doc-* skillSkill ExecutionInvoked based on recommendation
工件类型参考链接
选中的doc-*技能技能执行根据推荐结果调用

Version Information

版本信息

Version: 1.0.0 Created: 2025-11-29 Status: Active Author: AI Dev Flow Framework Team
版本: 1.0.0 创建时间: 2025-11-29 状态: 活跃 作者: AI Dev Flow Framework Team