agent-skill-discovery

agent-skill-discovery

用途

自动盘点两个范围内的 AI CLI 资源：系统上已安装的资源，以及当前仓库中存在的资源。此技能提供全面且与平台无关的目录，列出当前环境中可用的插件、Agent、技能和 MCP 服务。

此技能仅以发现模式运行——扫描、列出并呈现资源，不执行分析、推荐或编排。它是所有受支持 AI CLI 平台资源感知能力的基础层。

使用时机

在以下情况下调用此技能：

• 用户想了解已安装了哪些资源
• 规划复杂任务之前（作为编排的基础）
• 调试缺失的资源或功能
• 审核可用的工具和集成
• 发现新安装的插件或 MCP 服务
• 设置后验证技能是否安装
• 了解平台功能
• 检查当前仓库是否包含本地 Agent、技能或 MCP 配置

进度跟踪

每个步骤开始前显示进度指示，让用户了解进展：

[████░░░░░░░░░░░░░░░░] 15% — Step 1/6: Scanning Plugins
[████████░░░░░░░░░░░░] 30% — Step 2/6: Scanning Skills
[████████████░░░░░░░░] 45% — Step 3/6: Scanning MCP Servers
[████████████████░░░░] 60% — Step 4/6: Scanning Repository
[██████████████████░░] 75% — Step 5/6: Applying Filters
[████████████████████] 100% — Step 6/6: Generating Catalog

并行扫描策略

平台检测（步骤 0）完成后，在一个区块中启动步骤 1–4，作为四个并行 Agent：

Agent	角色
PluginScanner	使用 Glob 查找 plugin.json 文件，提取名称、版本和 Agent 元数据
SkillScanner	使用 Glob 查找 SKILL.md 文件，解析 YAML frontmatter，提取名称、描述和触发条件
McpScanner	读取 .mcp.json，针对每个服务运行 ToolSearch，并构建工具清单
RepoScanner	扫描当前工作目录中的本地 Agent、技能和 MCP 配置

每个 Agent 提示词的标题：# {AgentName} — Resource Discovery Agent

等待四个 Agent 全部完成，然后应用筛选条件（步骤 5）并生成目录（步骤 6）。

工作流

步骤 0：平台检测

目标： 确定正在执行此技能的 AI CLI 平台。

检测策略：

按顺序检查特定于平台的基础目录：

# Platform detection by directory existence
if [ -d "$HOME/.claude/skills" ] && [ -f "$HOME/.claude/skills/agent-skill-discovery/SKILL.md" ]; then
    PLATFORM="claude"
    BASE_DIR="$HOME/.claude"
elif [ -d "$HOME/.copilot/skills" ] && [ -f "$HOME/.copilot/skills/agent-skill-discovery/SKILL.md" ]; then
    PLATFORM="copilot"
    BASE_DIR="$HOME/.copilot"
elif [ -d "$HOME/.gemini/skills" ] && [ -f "$HOME/.gemini/skills/agent-skill-discovery/SKILL.md" ]; then
    PLATFORM="gemini"
    BASE_DIR="$HOME/.gemini"
elif [ -d "$HOME/.opencode/skills" ] && [ -f "$HOME/.opencode/skills/agent-skill-discovery/SKILL.md" ]; then
    PLATFORM="opencode"
    BASE_DIR="$HOME/.opencode"
elif [ -d "$HOME/.codex/skills" ] && [ -f "$HOME/.codex/skills/agent-skill-discovery/SKILL.md" ]; then
    PLATFORM="codex"
    BASE_DIR="$HOME/.codex"
else
    PLATFORM="unknown"
    BASE_DIR="$HOME"
fi

平台配置：

所有 5 个平台的平台配置相同——pluginsDir、skillsDir 和 mcpConfig 路径相对于 BASE_DIR 的结构一致。后续构建所有路径时，使用上文检测得出的 BASE_DIR。

步骤 1：扫描插件

目标： 发现所有已安装的插件及其 Agent。

操作：

使用 Glob 查找插件清单：

# Search for plugin.json files
Glob pattern: "{config.pluginsDir}/*/plugin.json"

对找到的每个插件：

1. 读取插件清单：

   Read: {plugin_path}/plugin.json
   

2. 提取元数据：

   • 插件名称
   • 插件版本
   • 插件描述
   • Agent 数组

3. 解析 Agent 详细信息： 对于 Agent 数组中的每个 Agent：

   • Agent 名称
   • Agent 描述
   • 可用工具（Glob、Grep、Read、Write、Bash 等）
   • Agent 颜色/类别（若已指定）

数据结构：

{
  "name": "feature-dev",
  "version": "1.0.0",
  "description": "Feature development workflow automation",
  "agents": [
    {
      "name": "code-explorer",
      "description": "Deeply analyzes existing codebase features",
      "tools": ["Glob", "Grep", "Read", "Bash"]
    },
    {
      "name": "code-architect",
      "description": "Designs feature architectures",
      "tools": ["Glob", "Grep", "Read", "Write"]
    }
  ]
}

容错处理：

• 如果插件目录不存在：返回空插件数组
• 如果 plugin.json 格式错误：记录警告，跳过该插件并继续
• 如果缺少 Agent 数组：将该插件计入，Agent 数量记为 0

步骤 2：扫描技能

目标： 发现所有已安装的技能及其元数据。

操作：

使用 Glob 查找技能定义：

# Search for SKILL.md files
Glob pattern: "{config.skillsDir}/*/SKILL.md"

对找到的每项技能：

1. 读取技能文件：

   Read: {skill_path}/SKILL.md
   

2. 解析 YAML frontmatter： 提取 --- 分隔符之间的 YAML 区块：

   ---
   name: skill-creator
   description: "This skill should be used when..."
   triggers:
     - "create a skill"
     - "new skill"
   version: 1.0.0
   category: development
   ---
   

3. 提取元数据：

   • 技能名称
   • 描述
   • 触发条件（短语数组）
   • 版本
   • 类别
   • 标签（若存在）

数据结构：

{
  "name": "skill-creator",
  "version": "1.0.0",
  "description": "This skill should be used when the user wants to create a new skill",
  "category": "development",
  "triggers": ["create a skill", "new skill", "build a skill"],
  "tags": ["automation", "scaffolding"]
}

容错处理：

• 如果技能目录不存在：返回空技能数组
• 如果 SKILL.md 没有 YAML frontmatter：跳过该技能并继续
• 如果缺少必填字段（名称、描述）：记录警告并跳过
• 如果触发条件为空：将该技能计入，触发条件数组留空

步骤 3：扫描 MCP 服务

目标： 发现已配置的 MCP 服务及其可用工具。

操作：

3.1 读取 MCP 配置：

# Check if MCP config exists
Read: {config.mcpConfig}

如果文件存在，则解析 JSON：

{
  "mcpServers": {
    "claude_ai_Notion": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-notion"]
    },
    "plugin_playwright": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/playwright-mcp/index.js"]
    }
  }
}

3.2 发现可用工具：

对每个已配置的 MCP 服务，使用 ToolSearch 和模式 mcp__{server_name}__* 列出可用工具。根据结果构建工具清单。如果 ToolSearch 失败，将该服务的工具标记为“不可用”并继续。

3.3 构建 MCP 服务清单：

{
  "name": "claude_ai_Notion",
  "type": "stdio",
  "command": "npx -y @anthropic-ai/mcp-server-notion",
  "tools": [
    {
      "name": "notion-search",
      "fullName": "mcp__claude_ai_Notion__notion-search",
      "description": "Search Notion pages and databases"
    },
    {
      "name": "notion-create-pages",
      "fullName": "mcp__claude_ai_Notion__notion-create-pages",
      "description": "Create new Notion pages"
    }
  ],
  "toolCount": 5
}

异常处理：

• 如果 .mcp.json 不存在：返回空 MCP 数组
• 如果 .mcp.json 格式错误：记录警告，返回空数组
• 如果 ToolSearch 失败：继续处理服务信息，并将工具标记为“不可用”
• 如果服务没有找到任何工具：仍将该服务列入清单，toolCount = 0

步骤 4：扫描当前仓库

目标： 发现用户当前工作所在仓库中的本地资源。

范围：

从当前工作目录开始扫描（如可用，则从仓库根目录开始）。不要使用硬编码的绝对路径。

4.1 发现本地 Agent：

按常见约定搜索 Agent 清单：

• 包含 agents 数组的 **/plugin.json 文件
• **/agents/*.md 和 **/agents/*.json
• **/.claude/agents/* 及类似的平台本地 Agent 文件夹

对每个候选项：

• 安全解析（JSON/YAML/Markdown 元数据）
• 提取 Agent 名称、描述和来源路径
• 将资源范围标记为 local

4.2 发现本地技能：

按常见约定搜索技能定义：

• **/skills/*/SKILL.md
• **/.*/skills/*/SKILL.md（仓库中的隐藏平台文件夹）

使用与已安装技能相同的验证规则解析 YAML frontmatter。

4.3 发现本地 MCP 配置：

按常见约定搜索 MCP 配置文件：

• ./.mcp.json
• ./mcp.json
• ./.config/mcp.json
• **/.mcp.json（嵌套工作区文件夹）

如果存在多个文件：

• 解析所有有效配置
• 按服务名称合并
• 根据服务名称 + 命令，与已安装范围内的配置去重

4.4 去重规则：

• 将已安装和本地清单分别置于独立部分
• 在每个部分内，按规范化名称去重
• 如果同一资源同时出现在两个范围内，则保留两条记录并明确标注范围

异常处理：

• 如果仓库没有本地资源：返回空的本地数组
• 如果本地文件格式错误：跳过该文件并继续扫描
• 如果无法确定仓库根目录：回退到当前工作目录

步骤 5：应用筛选条件（可选）

目标： 根据用户指定的条件筛选结果。

筛选类型：

5.1 按资源类型：

# User request: "list only plugins"
# Filter: Show only plugins, hide skills and MCPs

# User request: "show MCP servers"
# Filter: Show only MCP servers, hide plugins and skills

5.2 按类别：

# User request: "show development skills"
# Filter: skills.filter(s => s.category === 'development')

# User request: "list content tools"
# Filter: skills.filter(s => s.category === 'content')

5.3 按关键词搜索：

按关键词筛选：对插件名称、技能名称和描述、触发短语、MCP 服务名称及工具名称进行不区分大小写的子字符串匹配。仅返回匹配项。

筛选意图识别：

根据用户请求识别筛选意图：

• “only”“just”“show me” → 类型筛选
• “related to”“about”“for” → 关键词搜索
• 类别名称（development、content、analysis）→ 类别筛选

步骤 6：生成目录

目标： 以清晰、结构化的 Markdown 呈现已发现的资源。

输出格式：

# 📦 Resource Discovery Report

**Platform:** {platform_name}
**Scan Date:** {YYYY-MM-DD HH:MM:SS}

---

# 📦 Installed Resources

## 🔌 Plugins ({count})

### {plugin_name} v{version}
**Description:** {description}

**Agents ({count}):**
- `{agent_name}` - {description}
  - **Tools:** {tool1}, {tool2}, {tool3}

---

## 🛠️ Skills ({count})

### {skill_name} v{version}
**Description:** {description}
**Category:** {category}
**Triggers:** `{trigger1}`, `{trigger2}`, `{trigger3}`

---

## 🌐 MCP Servers ({count})

### {server_name} ({type})
**Status:** {✅ Connected | ⚠️ Disconnected}
**Command:** `{command} {args}`

**Tools ({count}):**
- `{tool_name}` - {description}

---

# 📁 Current Repository Resources

**Repository Path:** {cwd}

## 🔌 Local Agents ({count})

### {agent_name}
**Description:** {description}
**Source:** `{relative_path}`

## 🛠️ Local Skills ({count})

### {skill_name} v{version}
**Description:** {description}
**Source:** `{relative_path}`

## 🌐 Local MCP Servers ({count})

### {server_name} ({type|unknown})
**Source Config:** `{relative_path}`
**Command:** `{command_or_unknown}`

---

## 📊 Summary

- **Installed Plugins:** {count}
- **Installed Agents:** {count}
- **Installed Skills:** {count}
- **Installed MCP Servers:** {count}
- **Installed MCP Tools:** {count}
- **Local Agents:** {count}
- **Local Skills:** {count}
- **Local MCP Servers:** {count}

展示规则：

1. 资源数量：

   • 始终在各部分标题中显示数量
   • 在底部附上汇总

2. 排序：

   • 插件/Agent/技能/MCP：按名称的字母顺序排列

3. 空部分：

   • 如果未找到已安装资源：显示“未安装”
   • 如果当前仓库中未找到本地资源：显示“在当前仓库中未找到”
   • 示例：## 🔌 Plugins (0)\n\nNone installed.

4. 工具列表：

   • 对于 Agent：以逗号分隔的工具名称
   • 对于 MCP 服务：使用带描述的项目符号列表

5. 状态指示器：

   • MCP 已连接：✅
   • MCP 已断开：⚠️
   • 状态未知：❓

关键规则

绝不：

• ❌ 将平台名称或路径硬编码（始终动态检测）
• ❌ 假设目录结构存在（先检查，并妥善处理）
• ❌ 执行任何资源（仅读取和列出）
• ❌ 分析或推荐资源（这是编排器的工作）
• ❌ 跳过平台检测步骤
• ❌ 在没有检测上下文的情况下使用特定平台的工具名称
• ❌ 因单个资源格式错误而失败（跳过并继续）
• ❌ 对缺失的元数据做出假设（使用默认值或跳过）
• ❌ 用户要求完整发现时省略仓库范围

始终：

• ✅ 在运行时自动检测平台
• ✅ 动态扫描资源（每次都重新发现）
• ✅ 使用 Glob 发现文件（不要使用硬编码的 ls 或 find）
• ✅ 使用 Read 解析 JSON/YAML（不要使用 cat 或 grep）
• ✅ 妥善处理缺失的目录/文件（返回空数组，而不是报错）
• ✅ 提供清晰、结构化的 Markdown 输出
• ✅ 在所有部分中包含资源数量
• ✅ 在标题中显示平台名称和时间戳
• ✅ 除已安装范围外，也扫描当前仓库
• ✅ 将已安装资源和仓库资源分成不同的部分显示
• ✅ 在各部分中按字母顺序排列资源
• ✅ 解析前验证 JSON/YAML（使用 try-catch）

发现原则：

• 零配置： 在运行时发现路径，绝不硬编码
• 安全失败： 缺失资源时返回空数组，而不是报错
• 平台无关： 在所有 5 个平台上使用相同的输出格式
• 双重范围： 始终检查已安装范围和当前仓库范围
• 只读： 绝不修改、执行或推荐资源
• 全新扫描： 不缓存，每次调用都重新扫描

使用示例

示例 1：完整清单

用户请求：

"What do I have installed?"

输出：

# 📦 Installed Resources

**Platform:** Claude Code
**Scan Date:** 2026-02-07 14:32:15

---

## 🔌 Plugins (3)

### commit-commands v1.0.0
**Description:** Git commit workflow automation

**Agents (3):**
- `commit` - Create git commits with best practices
  - **Tools:** Bash, Read, Grep
- `commit-push-pr` - Commit, push, and open pull request
  - **Tools:** Bash, Read, Grep
- `clean_gone` - Clean up deleted remote branches
  - **Tools:** Bash

### feature-dev v1.2.0
**Description:** Feature development workflow automation

**Agents (3):**
- `code-explorer` - Deeply analyzes existing codebase
  - **Tools:** Glob, Grep, Read, Bash
- `code-architect` - Designs feature architectures
  - **Tools:** Glob, Grep, Read, Write, Bash
- `code-reviewer` - Reviews code for quality issues
  - **Tools:** Glob, Grep, Read, Bash

### plugin-dev v1.0.0
**Description:** Claude Code plugin development tools

**Agents (5):**
- `create-plugin` - Guided plugin creation workflow
  - **Tools:** Read, Write, Bash
- `skill-development` - Skill creation and optimization
  - **Tools:** Read, Write, Grep
- `command-development` - Slash command development
  - **Tools:** Read, Write
- `hook-development` - Plugin hook development
  - **Tools:** Read, Write, Grep
- `agent-development` - Agent creation and configuration
  - **Tools:** Read, Write

---

## 🛠️ Skills (8)

### agent-skill-discovery v1.0.0
**Description:** This skill should be used when the user wants to see all installed resources
**Category:** discovery
**Triggers:** `what do I have installed`, `list available resources`, `show my agents`

### audio-transcriber v1.0.0
**Description:** Transform audio recordings into professional Markdown documentation
**Category:** content
**Triggers:** `transcribe audio`, `convert audio to text`

### prompt-engineer v1.0.0
**Description:** Transforms user prompts into optimized prompts using frameworks
**Category:** optimization
**Triggers:** `improve this prompt`, `optimize prompt`, `enhance prompt`

### skill-creator v1.0.0
**Description:** This skill should be used when the user asks to create a new skill
**Category:** development
**Triggers:** `create a skill`, `new skill`, `build a skill`

### youtube-summarizer v1.0.0
**Description:** Extract transcripts from YouTube videos and generate summaries
**Category:** content
**Triggers:** `summarize youtube`, `youtube summary`, `analyze video`

(... 3 more skills)

---

## 🌐 MCP Servers (2)

### claude_ai_Notion (stdio)
**Status:** ✅ Connected
**Command:** `npx -y @anthropic-ai/mcp-server-notion`

**Tools (5):**
- `notion-search` - Search Notion pages and databases
- `notion-create-pages` - Create new Notion pages
- `notion-fetch` - Fetch Notion page content
- `notion-update-page` - Update existing Notion pages
- `notion-get-users` - Get Notion workspace users

### plugin_playwright (stdio)
**Status:** ✅ Connected
**Command:** `node /Users/user/.claude/plugins/playwright/index.js`

**Tools (15):**
- `browser_navigate` - Navigate to URL
- `browser_click` - Click element
- `browser_type` - Type text into element
- `browser_screenshot` - Take screenshot
- `browser_evaluate` - Run JavaScript in browser
(... 10 more tools)

---

## 📊 Summary

- **Total Plugins:** 3
- **Total Agents:** 11
- **Total Skills:** 8
- **Total MCP Servers:** 2
- **Total MCP Tools:** 20

示例 2：按类型筛选

用户请求：

"List only MCP servers"

输出：

# 📦 MCP Servers (2)

**Platform:** GitHub Copilot CLI
**Scan Date:** 2026-02-07 14:35:42

---

### claude_ai_Notion (stdio)
**Status:** ✅ Connected
**Tools (5):**

（其余输出沿用相同的目录格式——仅显示匹配的资源类型。）

示例 3：关键词搜索

用户请求：

"Show skills related to content"

输出：

# 📦 Skills - Search Results for "content" (2)

**Platform:** Gemini CLI
**Scan Date:** 2026-02-07 14:38:10

---

### audio-transcriber v1.0.0
**Description:** Transform audio recordings into professional Markdown documentation
**Category:** content

（其余输出沿用相同的目录格式——仅显示匹配的资源类型。）

示例 4：无结果

用户请求：

"What do I have installed?"

输出（全新安装）：

# 📦 Installed Resources

**Platform:** OpenCode
**Scan Date:** 2026-02-07 14:40:33

---

## 🔌 Plugins (0)

None installed.

（其余输出沿用相同的目录格式——仅显示匹配的资源类型。）