Capability Discovery Skill

This skill enables dynamic discovery and mapping of installed plugins to abstract capability categories, allowing the workflow to route tasks to appropriate agents without hardcoding plugin names. It includes explicit delegation announcements so users understand routing decisions.

Core Principles

• Technology Agnostic: Map capabilities, not specific plugins

• Dynamic Discovery: Scan at runtime, not compile time

• Graceful Fallback: Use internal default agents when no plugin matches

• Project-Aware Routing: Prefer plugins matching detected project type

• Transparent Delegation: Always announce why a particular agent was chosen

Capability Categories

Capability Purpose Phase Default Agent

requirements-gathering

Structured requirements elicitation DISCUSS defaults/interviewer

brainstorming

Ideation and option exploration DISCUSS defaults/interviewer

codebase-analysis

Understanding existing code DISCUSS, PLAN defaults/researcher

tdd-implementation

Test-driven development EXECUTE defaults/executor

code-implementation

General code writing EXECUTE defaults/executor

infrastructure

DevOps/infra tasks EXECUTE defaults/executor

code-review

Quality validation VERIFY validator

requirements-validation

Requirements compliance VERIFY validator

Discovery Process

Step 1: Enumerate Installed Plugins

1. Locate Plugins/ directory
2. List all subdirectories (each is a plugin)
3. For each plugin: a. Read .claude-plugin/plugin.json for metadata b. Scan agents/.md for agent definitions c. Scan commands/.md for command definitions
4. Build plugin registry

Step 2: Extract Descriptions

For each agent/command file, extract the description from YAML frontmatter:

name: implementer description: TDD implementation specialist for .NET. Use to write minimal code that makes tests pass. model: opus tools: [Read, Write, Edit, Bash, Grep, Glob]

Step 3: Map to Capabilities (Keyword Scoring)

Apply keyword matching to descriptions:

For each plugin agent/command:

1. Tokenize description into words (lowercase)
2. Match against capability keywords
3. Calculate score:
   • Exact keyword match: +10 points
   • Partial match (word contains keyword): +3 points
   • Keyword in first sentence: +5 bonus
   • Multiple keywords from same category: +2 each after first
4. Assign to highest-scoring capability
5. Record match confidence (High: 25+, Medium: 15-24, Low: <15)

Step 4: Detect Project Type

Scan project root for technology indicators:

File Pattern Project Type Keywords

*.csproj , *.sln

dotnet .NET, dotnet, C#, csharp

package.json , *.js , *.ts

node Node.js, JavaScript, TypeScript

*.py , requirements.txt

python Python, pip, pytest

go.mod , *.go

go Go, golang

Cargo.toml , *.rs

rust Rust, Cargo

pom.xml , build.gradle

java Java, Maven, Gradle

Step 5: Cache Results in FLOW.md

Store capability mappings in the Capabilities Cache section of FLOW.md.

Delegation Priority System

When routing a task to an agent, follow this priority order:

Priority 1: Project-Type Match

If project is detected (e.g., dotnet), prefer plugins with matching technology keywords in their description.

Detected: dotnet project Capability needed: tdd-implementation

Matches:

• dotnet-tdd:implementer (description: "TDD for .NET") → Score: 35 + project bonus
• node-tdd:implementer (description: "TDD for Node.js") → Score: 30

Winner: dotnet-tdd:implementer (project type match)

Priority 2: Exact Keyword Match

Prefer agents with exact keyword matches over partial matches.

Priority 3: Agent Over Command

When both an agent and a command match a capability, prefer the agent (more capable).

Priority 4: Internal Default

When no plugin matches the capability, use the appropriate default agent.

Delegation Announcement Pattern

CRITICAL: Always announce delegation decisions to the user with reasoning.

When Plugin Found

Delegating [capability] → [plugin-name]:[agent-name]

Matched via keyword scoring:

• Keywords: [matched keywords]
• Score: [score] (High confidence)
• Project type: [type] (matched)

Spawning agent...

When Using Default

Using built-in agent for [capability] → flow-workflow:defaults/[agent]

No installed plugin matched this capability.

• Searched: [N] plugins
• Keywords tried: [keywords]

Consider installing: [suggested plugin type]

Quick Delegation (For Status/Logs)

→ [capability]: [plugin:agent] (keyword match) → [capability]: defaults/[agent] (no plugin match)

Routing Logic

When Phase Needs Capability

1. Determine capability needed for current task
2. Look up FLOW.md capability cache
3. If cache stale (>24h) or missing, re-scan plugins
4. If multiple matches for capability: a. Filter by project type preference b. Prefer exact keyword matches c. Prefer agents over commands
5. If single match: a. Announce delegation with reasoning b. Return agent reference
6. If no match: a. Announce using default b. Return default agent reference

Capability → Phase Mapping

Phase Primary Capability Secondary Capabilities

DISCUSS requirements-gathering brainstorming, codebase-analysis

PLAN (internal coordinator) codebase-analysis

EXECUTE code-implementation tdd-implementation, infrastructure

VERIFY code-review requirements-validation

Default Agents

When no plugin matches a capability:

Capability Default Agent Location

requirements-gathering interviewer flow-workflow:defaults/interviewer

brainstorming interviewer flow-workflow:defaults/interviewer

codebase-analysis researcher flow-workflow:defaults/researcher

tdd-implementation executor flow-workflow:defaults/executor

code-implementation executor flow-workflow:defaults/executor

infrastructure executor flow-workflow:defaults/executor

code-review validator flow-workflow:validator

requirements-validation validator flow-workflow:validator

Re-Discovery Triggers

Re-scan plugins when:

• /flow-workflow:start is run on uninitialized project

• FLOW.md capability cache is older than 24 hours

• Requested capability returns no match (try fresh scan)

• User explicitly requests refresh via /flow-workflow:status --refresh

Capability Gap Logging

When no plugin matches a capability, log in FLOW.md:

Capability Warnings

[TIMESTAMP]: No plugin found for capability 'infrastructure'

• Searched: 5 plugins
• Keywords tried: infra, devops, pipeline, deploy
• Using: flow-workflow:defaults/executor
• Suggestion: Consider installing a DevOps plugin

Integration Points

• State Management: Cache capability map in FLOW.md

• Coordinator Agent: Performs discovery on initialization, uses for routing

• Smart Continuation: Uses cached capabilities for agent selection

See categories.md for detailed capability category definitions.