capability-discovery

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

本Skill可实现已安装插件到抽象能力类别的动态发现与映射，允许工作流在无需硬编码插件名称的情况下将任务路由至合适的Agent。它包含显式的委托通知，以便用户理解路由决策。

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

技术无关性：映射能力而非特定插件
动态发现：在运行时扫描，而非编译时
优雅降级：当无匹配插件时使用内部默认Agent
项目感知路由：优先选择与检测到的项目类型匹配的插件
透明委托：始终说明选择特定Agent的原因

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

能力	用途	阶段	默认Agent
`requirements-gathering`	结构化需求获取	DISCUSS	defaults/interviewer
`brainstorming`	构思与方案探索	DISCUSS	defaults/interviewer
`codebase-analysis`	理解现有代码	DISCUSS, PLAN	defaults/researcher
`tdd-implementation`	测试驱动开发	EXECUTE	defaults/executor
`code-implementation`	通用代码编写	EXECUTE	defaults/executor
`infrastructure`	DevOps/基础设施任务	EXECUTE	defaults/executor
`code-review`	质量验证	VERIFY	validator
`requirements-validation`	需求合规性检查	VERIFY	validator

Discovery Process

发现流程

Step 1: Enumerate Installed Plugins

步骤1：枚举已安装插件

markdown

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

markdown

1. 定位Plugins/目录
2. 列出所有子目录（每个子目录对应一个插件）
3. 针对每个插件：
   a. 读取.claude-plugin/plugin.json获取元数据
   b. 扫描agents/*.md获取Agent定义
   c. 扫描commands/*.md获取命令定义
4. 构建插件注册表

Step 2: Extract Descriptions

步骤2：提取描述信息

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

yaml

---
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]
---

从每个Agent/命令文件的YAML前置元数据中提取描述：

yaml

---
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)

步骤3：映射到能力类别（关键词评分）

Apply keyword matching to descriptions:

markdown

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)

对描述信息应用关键词匹配：

markdown

针对每个插件的Agent/命令：
  1. 将描述拆分为单词（小写）
  2. 与能力关键词匹配
  3. 计算分数：
     - 精确关键词匹配：+10分
     - 部分匹配（单词包含关键词）：+3分
     - 关键词位于第一句：+5分奖励
     - 同一类别多个关键词：第一个之后每个+2分
  4. 分配至得分最高的能力类别
  5. 记录匹配置信度（高：25+，中：15-24，低：<15）

Step 4: Detect Project Type

步骤4：检测项目类型

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

扫描项目根目录的技术标识文件：

文件模式	项目类型	关键词
`.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

步骤5：在FLOW.md中缓存结果

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

将能力映射存储在FLOW.md的Capabilities Cache部分。

Delegation Priority System

委托优先级系统

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

将任务路由至Agent时，遵循以下优先级顺序：

Priority 1: Project-Type Match

优先级1：项目类型匹配

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

markdown

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)

如果检测到项目类型（如dotnet），优先选择描述中包含匹配技术关键词的插件。

markdown

检测到：dotnet项目
所需能力：tdd-implementation

匹配结果：
- dotnet-tdd:implementer（描述："TDD for .NET"）→ 得分：35 + 项目匹配奖励
- node-tdd:implementer（描述："TDD for Node.js"）→ 得分：30

胜出者：dotnet-tdd:implementer（项目类型匹配）

Priority 2: Exact Keyword Match

优先级2：精确关键词匹配

Prefer agents with exact keyword matches over partial matches.

优先选择精确关键词匹配的Agent，而非部分匹配。

Priority 3: Agent Over Command

优先级3：Agent优先于命令

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

当Agent和命令均匹配某一能力时，优先选择Agent（功能更全面）。

Priority 4: Internal Default

优先级4：内部默认Agent

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

当无插件匹配该能力时，使用合适的默认Agent。

Delegation Announcement Pattern

委托通知模板

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

关键要求：始终向用户通知委托决策及理由。

When Plugin Found

找到匹配插件时

markdown

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

Matched via keyword scoring:
- Keywords: [matched keywords]
- Score: [score] (High confidence)
- Project type: [type] (matched)

Spawning agent...

markdown

**正在委托[capability]** → [plugin-name]:[agent-name]

通过关键词评分匹配：
- 匹配关键词：[matched keywords]
- 得分：[score]（高置信度）
- 项目类型：[type]（匹配）

正在启动Agent...

When Using Default

使用默认Agent时

markdown

**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]

markdown

**使用内置Agent**处理[capability] → flow-workflow:defaults/[agent]

无已安装插件匹配该能力。
- 已搜索：[N]个插件
- 尝试的关键词：[keywords]

建议安装：[suggested plugin type]

Quick Delegation (For Status/Logs)

快速委托（用于状态/日志）

markdown

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

markdown

→ [capability]: [plugin:agent]（关键词匹配）
→ [capability]: defaults/[agent]（无插件匹配）

Routing Logic

路由逻辑

When Phase Needs Capability

当阶段需要特定能力时

markdown

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

markdown

1. 确定当前任务所需的能力
2. 查阅FLOW.md中的能力缓存
3. 如果缓存过期（>24小时）或缺失，重新扫描插件
4. 如果某一能力存在多个匹配项：
   a. 按项目类型偏好筛选
   b. 优先选择精确关键词匹配
   c. 优先选择Agent而非命令
5. 如果仅有一个匹配项：
   a. 通知委托决策及理由
   b. 返回Agent引用
6. 如果无匹配项：
   a. 通知将使用默认Agent
   b. 返回默认Agent引用

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

阶段	主要能力	次要能力
DISCUSS	requirements-gathering	brainstorming, codebase-analysis
PLAN	(internal coordinator)	codebase-analysis
EXECUTE	code-implementation	tdd-implementation, infrastructure
VERIFY	code-review	requirements-validation

Default Agents

默认Agent

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

当无插件匹配能力时使用：

能力	默认Agent	位置
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
```

在以下情况时重新扫描插件：

在未初始化的项目上运行
```
/flow-workflow:start
```
FLOW.md中的能力缓存已超过24小时
请求的能力无匹配结果（尝试重新扫描）
用户通过
```
/flow-workflow:status --refresh
```
显式请求刷新

Capability Gap Logging

能力缺口日志

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

markdown

undefined

当无插件匹配能力时，在FLOW.md中记录：

markdown

undefined

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

undefined

[TIMESTAMP]: 未找到匹配capability 'infrastructure'的插件

已搜索：5个插件
尝试的关键词：infra, devops, pipeline, deploy
当前使用：flow-workflow:defaults/executor
建议：考虑安装DevOps插件

undefined

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.

状态管理：在FLOW.md中缓存能力映射
协调Agent：在初始化时执行发现流程，并将结果用于路由
智能续行：使用缓存的能力信息选择Agent

详细的能力类别定义请参见

categories.md

。