majiayu000 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 |
| execution plans | iplan, execution, session | doc-iplan |
| 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 |
| doc-iplan | core-workflow | 12 | Execution Plans |
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