skill-capability-matcher

What this skill does

# Skill Capability Matcher

Match natural language requirements to available skills, designing an optimal workflow step sequence.

## Purpose

Parse user's workflow description, understand their intent, and recommend which skills should handle each part of the workflow. Output includes step IDs, skill names, missions, and data flow.

## Process

### Step 1: Parse Requirements

Extract from the user's description:

**Input Types:**
- video transcript
- audio transcript
- article/blog post
- documentation
- raw text
- structured data (JSON/YAML)

**Processing Goals:**
- analyze (deep understanding)
- summarize (condensation)
- generate (create new content)
- transform (change format)
- extract (pull specific data)
- validate (check correctness)

**Output Format:**
- JSON structure
- Markdown document
- Summary text
- Structured data

### Step 2: Load Registry

Read the plugin registry from registry-loader output (v0.7.0):

```json
{
  "plugins": [...],
  "summary": { "totalSkills": N, "installedSkills": N, "availableSkills": N }
}
```

Build a capability index from skill descriptions and inferred capabilities.
Include `installed` status when scoring - prefer installed skills for immediate execution.

### Step 3: Match Capabilities

Score each skill by:
1. **Description match** - Does skill description align with requirements?
2. **Capability overlap** - Do inferred capabilities match processing goals?
3. **Input/output compatibility** - Can skill handle input type and produce expected output?

### Step 4: Design Step Sequence

For each matched skill:
1. Create a step ID (kebab-case, descriptive)
2. Determine dependencies (`needs:`)
3. Write a mission description (what to accomplish)
4. Define data flow (input → output)

### Step 5: Recommend Sequence

Order skills logically:
1. Analysis skills first (understand content)
2. Generation/transformation skills second
3. Assembly/output skills last

Ensure proper data dependencies.

### Step 6: Flag Gaps

If requirements can't be fully satisfied:
- List unmatched capabilities as gaps
- Suggest creating custom skills if needed
- Indicate if workflow is partial

## Input

Provide:
1. User's natural language description
2. Registry JSON from plugin-registry-scanner

## Output Schema

```json
{
  "requirements": {
    "inputType": "video transcript",
    "goals": ["extract key points", "generate outline"],
    "outputFormat": "structured JSON"
  },
  "recommendations": [
    {
      "skill": "media-reviewer",
      "suggestedStepId": "analyze-content",
      "goalId": "analyze",
      "matchScore": 0.92,
      "capabilities": ["content analysis", "theme extraction"],
      "mission": "Deep analysis of video transcript. Extract key themes, quotes, and narrative structure.",
      "rationale": "Primary skill for content understanding"
    },
    {
      "skill": "idea-synthesis",
      "suggestedStepId": "generate-ideas",
      "goalId": "generate",
      "matchScore": 0.85,
      "capabilities": ["idea generation", "hooks and angles"],
      "mission": "Generate hooks, angles, and questions from the analysis. Read user profile for personalization.",
      "rationale": "Creates engaging content ideas from analysis"
    }
  ],
  "suggestedSequence": ["analyze-content", "generate-ideas", "build-output"],
  "dataFlow": {
    "analyze-content": {
      "needs": [],
      "provides": "analysis.json"
    },
    "generate-ideas": {
      "needs": ["analyze-content"],
      "provides": "ideas.json"
    },
    "build-output": {
      "needs": ["analyze-content", "generate-ideas"],
      "provides": "output.json"
    }
  },
  "gaps": [],
  "customSkillNeeded": false,
  "clarificationNeeded": true,
  "clarifications": {
    "sections": [
      {
        "id": "input",
        "title": "Input",
        "completed": false,
        "questions": [
          {
            "id": "content-type",
            "text": "What type of content will this workflow process?",
            "type": "single-select",
            "options": [
              { "id": "video", "label": "Video transcripts", "inferred": true },
              { "id": "audio", "label": "Audio transcripts" },
              { "id": "text", "label": "Text articles" },
              { "id": "web", "label": "Web pages (fetched via search)" }
            ],
            "reason": "Inferred 'video' from description, confirm or change"
          }
        ]
      },
      {
        "id": "goals",
        "title": "Goals",
        "completed": false,
        "questions": [
          {
            "id": "primary-goal",
            "text": "What are the primary goals for this workflow?",
            "type": "multi-select",
            "options": [
              { "id": "analyze", "label": "Analyze and extract key insights" },
              { "id": "summarize", "label": "Create structured summaries" },
              { "id": "generate", "label": "Generate creative content ideas" },
              { "id": "document", "label": "Build comprehensive reports" }
            ]
          },
          {
            "id": "depth",
            "text": "How deep should the analysis be?",
            "type": "single-select",
            "options": [
              { "id": "quick", "label": "Quick overview (1-2 key points)" },
              { "id": "standard", "label": "Standard analysis (5-7 key points)" },
              { "id": "deep", "label": "Deep analysis (comprehensive)" }
            ]
          }
        ]
      },
      {
        "id": "output",
        "title": "Output",
        "completed": false,
        "questions": [
          {
            "id": "format",
            "text": "What output format do you need?",
            "type": "single-select",
            "options": [
              { "id": "json", "label": "Structured JSON" },
              { "id": "markdown", "label": "Markdown document" },
              { "id": "both", "label": "Both JSON and Markdown" }
            ]
          }
        ]
      },
      {
        "id": "review",
        "title": "Review",
        "completed": false,
        "questions": []
      }
    ]
  }
}
```

## Scoring Guidelines

| Match Type | Score |
|------------|-------|
| Exact capability match | 0.9-1.0 |
| Strong description overlap | 0.7-0.9 |
| Partial capability match | 0.5-0.7 |
| Weak/inferred match | 0.3-0.5 |
| No clear match | < 0.3 |

## Scoring Rubric

Use these concrete criteria when assigning scores:

### Relevance Score (Primary Factor)
- **90-100**: Skill's primary purpose directly addresses requirement
- **70-89**: Skill clearly capable of addressing requirement
- **50-69**: Skill partially addresses requirement
- **30-49**: Skill tangentially related
- **0-29**: Minimal or no relevance

### Completeness Score
- **90-100**: Skill fully addresses all aspects of requirement
- **70-89**: Skill addresses most aspects, minor gaps
- **50-69**: Skill addresses core need, notable gaps
- **Below 50**: Significant portions unaddressed

### Specificity Score
- **90-100**: Skill specifically designed for this exact use case
- **70-89**: Skill well-suited for use case category
- **50-69**: General-purpose skill applicable to use case
- **Below 50**: Very general skill with broad applicability

### Confidence Calculation

```
confidence = (relevance * 0.5) + (completeness * 0.3) + (specificity * 0.2)
```

**Minimum threshold: 60%** - Skills below this should not be recommended.

## Semantic Matching Guidelines

Match requirements to skills beyond simple keyword matching:

### 1. Synonym Recognition
Match conceptually equivalent terms:
- "authentication" ↔ "login", "session management", "user verification"
- "database" ↔ "data persistence", "storage", specific ORMs
- "analyze" ↔ "review", "examine", "inspect", "assess"
- "generate" ↔ "create", "produce", "synthesize", "build"

### 2. Hierarchical Matching
Understand skill scope and specificity:
- General skill may satisfy specific requirement (e.g., "api-client" for "REST calls")
- Prefer specific