| license | BSL-1.1 |
| name | dag-skills-matcher |
| description | Matches natural language task descriptions to appropriate skills using semantic similarity, ranks candidates by fit and performance history, and maintains the skill catalog. Use when assigning skills to DAG nodes, searching for the right skill for a task, ranking competing skills, or browsing the skill catalog. Activate on "find skill", "match skill", "which skill", "skill for this task", "skill catalog", "rank skills", "best skill". NOT for executing DAGs (use dag-runtime), creating skills (use skill-architect), or grading skills (use skill-grader). |
| allowed-tools | Read,Grep,Glob |
| metadata | {"category":"DAG Framework","tags":["dag","skills","matcher","find-skill","match-skill"]} |
| category | Agent & Orchestration |
| tags | ["dag","skill-matching","routing","selection","registry"] |
DAG Skills Matcher
Matches tasks to skills, ranks candidates, and maintains the skill catalog.
Decision Points
When to Retry vs. Escalate
task_description → extract_intent()
├─ fit_score ≥ 0.5 for top candidate?
│ ├─ YES → check NOT clauses
│ │ ├─ passes → assign skill
│ │ └─ fails → try next candidate
│ └─ NO → retry with broader search terms
│ └─ still no fit_score ≥ 0.5?
│ └─ escalate to skill-architect (new skill needed)
Search Strategy Selection
task_complexity = count(technical_terms, domain_words, constraints)
├─ complexity ≤ 3 → keyword_search_only
├─ 4-8 → keyword + semantic_similarity
└─ >8 → full_pipeline (keyword + semantic + domain_tags + thompson)
Ranking Threshold Decision
candidate_count → ranking_strategy
├─ 1-2 candidates → simple fit_score ranking
├─ 3-5 candidates → weighted: fit(0.5) + elo(0.3) + cost(0.2)
└─ >5 candidates → full scoring with thompson sampling
Cost vs. Quality Trade-off
task_priority + budget_constraints → selection_criteria
├─ high_priority + unlimited_budget → maximize fit_score + elo
├─ medium_priority → balanced scoring (default weights)
└─ low_priority + cost_sensitive → weight cost(0.5) + fit(0.3) + elo(0.2)
Failure Modes
Schema Drift
Symptoms: fit_scores consistently < 0.3, many "skill not found" escalations
Detection: If >20% of searches in 24h escalate to skill-architect
Fix: Update skill descriptions with recent task language patterns
Thompson Exploitation Lock-in
Symptoms: Same 2-3 skills always selected, no skill performance comparison data
Detection: If top skill selection rate > 80% for any domain over 100 tasks
Fix: Increase Thompson sampling beta parameter by 10%, force exploration
NOT-Clause Bypass
Symptoms: Skills assigned to incompatible tasks, high downstream failure rates
Detection: If downstream acceptance_rate < 0.7 for any skill
Fix: Strengthen NOT-clause checking, add regex patterns for exclusion terms
Semantic Similarity False Positives
Symptoms: Skills matched on superficial word similarity, not actual capability
Detection: If fit_score > 0.7 but downstream acceptance_rate < 0.5
Fix: Add domain-specific negative embeddings, weight keyword matching higher
Cost Optimization Trap
Symptoms: Always selecting cheapest skills, degrading output quality
: If avg_cost_per_use drops >30% while acceptance_rate drops >15%
: Set minimum fit_score threshold (0.5), reject candidates below threshold regardless of cost
