Workflow Matching Skill

When to Use This Skill

Use this skill when implementing workflow matching patterns in your codebase.

How to Use This Skill

Review the patterns and examples below
Apply the relevant patterns to your implementation
Follow the best practices outlined in this skill

Version: 1.0.0 Status: Production Category: Orchestration

Purpose

Intelligent workflow discovery and matching based on user intent analysis. This skill provides the core matching algorithm used by the use-case-analyzer agent and workflow commands.

Capabilities

Intent Parsing - Extract actions, entities, and constraints from natural language
Keyword Matching - Search workflow descriptions and tags
Semantic Matching - Understand meaning beyond exact keywords
Scoring - Rank matches by relevance, complexity fit, and agent availability
Composition - Identify when multiple workflows should be combined

Algorithm

Step 1: Intent Extraction

def extract_intent(query: str) -> Intent:
    """
    Parse user query into structured intent.

    Returns:
        Intent with action, domain, entities, constraints
    """
    # Action keywords
    actions = {
        "create": ["create", "build", "make", "generate", "add"],
        "analyze": ["analyze", "review", "evaluate", "assess", "check"],
        "automate": ["automate", "schedule", "trigger", "run"],
        "optimize": ["optimize", "improve", "enhance", "streamline"],
        "monitor": ["monitor", "track", "watch", "alert"],
        "migrate": ["migrate", "move", "transfer", "convert"],
    }

    # Domain keywords
    domains = {
        "software": ["code", "deploy", "test", "build", "api"],
        "business": ["sales", "marketing", "customer", "revenue"],
        "finance": ["budget", "invoice", "payment", "tax"],
        "hr": ["employee", "hire", "onboard", "payroll"],
    }

    # Extract from query
    return Intent(
        action=match_action(query, actions),
        domain=match_domain(query, domains),
        entities=extract_entities(query),
        constraints=extract_constraints(query)
    )

Step 2: Workflow Search

def search_workflows(intent: Intent, library: WorkflowLibrary) -> List[Match]:
    """
    Search workflow library for matches.

    Uses multiple strategies:
    1. Tag matching
    2. Description keyword search
    3. Step capability matching
    4. Category filtering
    """
    matches = []

    for workflow in library.workflows:
        score = 0

        # Tag matching (40%)
        tag_score = calculate_tag_overlap(intent.entities, workflow.tags)
        score += tag_score * 0.4

        # Description matching (30%)
        desc_score = calculate_text_similarity(intent.query, workflow.description)
        score += desc_score * 0.3

        # Capability matching (20%)
        cap_score = calculate_capability_fit(intent.action, workflow.steps)
        score += cap_score * 0.2

        # Complexity fit (10%)
        complexity_score = calculate_complexity_fit(intent.constraints, workflow.complexity)
        score += complexity_score * 0.1

        if score > 0.5:  # Threshold
            matches.append(Match(workflow, score))

    return sorted(matches, key=lambda m: m.score, reverse=True)

Step 3: Scoring Formula

Final Score = (Tag Match × 0.4) + (Description Match × 0.3) +
              (Capability Match × 0.2) + (Complexity Fit × 0.1)

Adjustments:
  +5%  if all required agents are available
  +3%  if workflow has high success rate
  -5%  if workflow complexity exceeds user constraint
  -10% if critical dependencies are missing

Usage

In use-case-analyzer Agent

# Import skill
from skills.workflow_matching import match_workflows

# Match workflows to intent
matches = match_workflows(
    query="I need to onboard enterprise customers with custom training",
    top_k=5,
    domain_filter="business"
)

for match in matches:
    print(f"{match.workflow.name}: {match.score}%")

In /analyze-workflow Command

# The command uses this skill internally
/analyze-workflow "quarterly financial reporting"

# Equivalent to:
Task(subagent_type="use-case-analyzer", prompt="""
Use workflow-matching skill to find workflows for:
"quarterly financial reporting"
""")

Configuration

Scoring Weights

# config/workflow-matching.yaml
scoring:
  tag_weight: 0.4
  description_weight: 0.3
  capability_weight: 0.2
  complexity_weight: 0.1

thresholds:
  minimum_score: 0.5
  high_confidence: 0.85

adjustments:
  agent_availability_bonus: 0.05
  success_rate_bonus: 0.03
  complexity_mismatch_penalty: 0.05
  missing_dependency_penalty: 0.10

Domain Mappings

domain_mappings:
  software:
    categories: [developer-experience, devops, quality-assurance]
    keywords: [code, deploy, test, build, api, release]

  business:
    categories: [business/sales, operations/process]
    keywords: [sales, marketing, customer, revenue, pipeline]

  finance:
    categories: [finance/investment, professional/hr]
    keywords: [budget, invoice, payment, tax, portfolio]

Output Format

Match Object

{
  "workflow": {
    "name": "customer-onboarding-automation",
    "category": "operations/process",
    "description": "End-to-end customer onboarding...",
    "complexity": "moderate",
    "steps": 10
  },
  "score": 92,
  "breakdown": {
    "tag_match": 95,
    "description_match": 88,
    "capability_match": 90,
    "complexity_fit": 100
  },
  "adjustments": {
    "agent_availability": "+5%",
    "success_rate": "+3%"
  },
  "agents_required": [
    "orchestrator",
    "codi-documentation-writer",
    "notification-specialist"
  ],
  "confidence": "high"
}

Integration Points

use-case-analyzer agent - Primary consumer
/analyze-workflow command - Command interface
workflow-orchestrator agent - Execution planning
workflow-index.json - Workflow catalog source

Performance

Metric	Value
Average match time	<100ms
Workflows searched	750
Categories indexed	14
Cache hit rate	~80%

Success Output

When this skill completes successfully, you should see:

✅ SKILL COMPLETE: workflow-matching

Completed:
- [x] Intent extracted from user query (action, domain, entities, constraints)
- [x] Workflow library searched across 750 workflows
- [x] Top 5 matches ranked by score with breakdown
- [x] Agent availability verified for top matches
- [x] Composition opportunities identified (if applicable)

Output:
Match 1: customer-onboarding-automation (Score: 92%)
  - Tag Match: 95% | Description: 88% | Capability: 90% | Complexity: 100%
  - Agents Available: orchestrator, codi-documentation-writer, notification-specialist
  - Confidence: HIGH

Match 2: sales-pipeline-automation (Score: 85%)
  - Tag Match: 88% | Description: 82% | Capability: 85% | Complexity: 85%
  - Agents Available: orchestrator, crm-integration-specialist
  - Confidence: MEDIUM

Workflow Recommendations: 2 high-confidence, 3 medium-confidence
Average Match Time: <100ms

Completion Checklist

Before marking this skill as complete, verify:

Intent extraction completed: action, domain, entities identified
Workflow search completed: minimum 5 matches returned (or fewer if library small)
Scoring calculated: tag, description, capability, complexity breakdown present
Agent availability checked: all required agents verified
Confidence levels assigned: HIGH (>85%), MEDIUM (70-85%), or LOW (<70%)
Composition detection: multi-workflow opportunities identified if relevant
Match time <100ms: performance within acceptable range
Output format valid: JSON structure matches specification
Cache utilized: if repeat query, cache hit occurred

Failure Indicators

This skill has FAILED if:

❌ Intent extraction returns empty or malformed intent object
❌ No workflows matched despite valid query and populated library
❌ Scoring breakdown missing or all zeros
❌ Agent availability not checked (missing "agents_required" field)
❌ Match time >500ms for standard library size (750 workflows)
❌ Output format invalid or missing required fields
❌ All matches below 50% threshold (indicates poor library coverage or query issue)
❌ Confidence levels not assigned or all LOW

When NOT to Use

Do NOT use workflow-matching when:

Direct workflow execution needed - Use workflow-execution skill to run known workflow
Workflow creation/editing - Use workflow-orchestrator agent for new workflows
Agent selection only - Use agent-discovery skill for simpler agent matching
Intent not clarified - If user query ambiguous, use ambiguity-handling first
Custom workflow required - If no existing workflow fits, create custom solution
Very specific domain - For niche use cases, manual workflow selection may be faster
Single workflow known - If user specifies exact workflow, skip matching

Alternative Approaches:

Direct workflow invocation: /run-workflow customer-onboarding
Agent-only matching: agent-discovery skill for simpler use cases
Manual workflow catalog browse: Review WORKFLOW-LIBRARY-INDEX.md
Use case analyzer: use-case-analyzer agent for broader analysis

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Skipping intent extraction	Poor match quality, irrelevant results	Always extract intent first
Using single scoring factor	Misses nuanced matches	Use weighted multi-factor scoring (tag 40%, description 30%, capability 20%, complexity 10%)
Ignoring agent availability	Recommend workflows that can't execute	Check agent availability before returning matches
No threshold filtering	Return low-quality matches (<50%)	Filter matches below 50% threshold
Caching without invalidation	Stale workflow recommendations	Invalidate cache when workflow library updates
Missing confidence levels	User can't assess match quality	Assign HIGH/MEDIUM/LOW confidence to each match
Ignoring complexity mismatch	Recommend overly complex workflows	Penalize complexity mismatch (-5%)
No composition detection	Miss multi-workflow opportunities	Check if combining workflows better than single match
Exact keyword matching only	Miss semantic equivalents	Use synonym expansion and semantic similarity
No domain filtering	Return irrelevant cross-domain matches	Filter by domain when specified in intent

Principles

This skill embodies these CODITECT principles:

Intent-First Approach - Understand user need before searching workflows
Multi-Factor Scoring - Holistic evaluation (tags + description + capability + complexity)
Agent-Aware Matching - Only recommend workflows with available agents
Performance First - <100ms match time through caching and indexing
Confidence Transparency - Explicit HIGH/MEDIUM/LOW confidence scoring
Composition Over Single Solution - Identify multi-workflow opportunities
Progressive Filtering - Threshold filtering (>50%) ensures quality
Semantic Understanding - Beyond keyword matching to meaning

Full Principles: CODITECT-STANDARD-AUTOMATION.md

Maintainer: CODITECT Core Team Last Updated: 2025-12-12

When to Use This Skill​

How to Use This Skill​

Purpose​

Capabilities​

Algorithm​

Step 1: Intent Extraction​

Step 2: Workflow Search​

Step 3: Scoring Formula​

Usage​

In use-case-analyzer Agent​

In /analyze-workflow Command​

Configuration​

Scoring Weights​

Domain Mappings​

Output Format​

Match Object​

Integration Points​

Performance​

Related Skills​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​