ericgandrade/claude-superskills/agent-skill-discovery

agent-skill-discovery

Purpose

Automated inventory of AI CLI resources across two scopes: resources installed on the system and resources present in the current repository. This skill provides a comprehensive, platform-agnostic catalog of plugins, agents, skills, and MCP servers available in the current environment.

The skill operates in discovery-only mode—it scans, lists, and presents resources without performing analysis, recommendations, or orchestration. It serves as the foundation layer for resource awareness across all supported AI CLI platforms.

When to Use

Invoke this skill when:

• User wants to know what resources are installed
• Before planning complex tasks (foundation for orchestration)
• Debugging missing resources or capabilities
• Auditing available tools and integrations
• Discovering newly installed plugins or MCP servers
• Verifying skill installation after setup
• Understanding platform capabilities
• Checking whether the current repository contains local agents, skills, or MCP configs

Progress Tracking

Display a progress gauge before each step to keep the user informed:

[████░░░░░░░░░░░░░░░░] 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

Parallel Scanning Strategy

After platform detection (Step 0), launch Steps 1–4 as four simultaneous agents in a single block:

Each agent prompt header: # {AgentName} — Resource Discovery Agent

Wait for all four to complete, then apply filters (Step 5) and generate catalog (Step 6).

Workflow

Step 0: Platform Detection

Objective: Identify which AI CLI platform is executing the skill.

Detection Strategy:

Check for platform-specific base directories in order:

# 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

Platform Configuration:

Platform configuration is uniform across all 5 platforms — pluginsDir, skillsDir, and mcpConfig paths follow the same structure relative to BASE_DIR. Use BASE_DIR resolved from the detection above for all subsequent path construction.

Step 1: Scan for Plugins

Objective: Discover all installed plugins and their agents.

Actions:

Use Glob to find plugin manifests:

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

For each plugin found:

1. Read plugin manifest:

``bash Read: {plugin_path}/plugin.json ``

1. Extract metadata:

• Plugin name
• Plugin version
• Plugin description
• Agents array

1. Parse agent details:

For each agent in the agents array:

• Agent name
• Agent description
• Available tools (Glob, Grep, Read, Write, Bash, etc.)
• Agent color/category (if specified)

Data Structure:

{
  "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"]
    }
  ]
}

Graceful Handling:

• If plugins directory doesn't exist: Return empty plugin array
• If plugin.json is malformed: Log warning, skip plugin, continue
• If agents array is missing: Include plugin with 0 agents

Step 2: Scan for Skills

Objective: Discover all installed skills and their metadata.

Actions:

Use Glob to find skill definitions:

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

For each skill found:

1. Read skill file:

``bash Read: {skill_path}/SKILL.md ``

1. Parse YAML frontmatter:

Extract the YAML block between --- delimiters: ```yaml

name: skill-creator description: "This skill should be used when..." triggers:

• "create a skill"
• "new skill"

version: 1.0.0 category: development

```

1. Extract metadata:

• Skill name
• Description
• Triggers (array of phrases)
• Version
• Category
• Tags (if present)

Data Structure:

{
  "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"]
}

Graceful Handling:

• If skills directory doesn't exist: Return empty skill array
• If SKILL.md has no YAML frontmatter: Skip skill, continue
• If required fields missing (name, description): Log warning, skip
• If triggers is empty: Include skill with empty triggers array

Step 3: Scan for MCP Servers

Objective: Discover configured MCP servers and their available tools.

Actions:

3.1 Read MCP Configuration:

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

If file exists, parse 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 Discover Available Tools:

Use ToolSearch with pattern mcp__{server_name}__* to list available tools for each configured MCP server. Build tool inventory from results. If ToolSearch fails, mark the server's tools as "unavailable" and continue.

3.3 Build MCP Server Inventory:

{
  "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
}

Graceful Handling:

• If .mcp.json doesn't exist: Return empty MCP array
• If .mcp.json is malformed: Log warning, return empty array
• If ToolSearch fails: Continue with server info, mark tools as "unavailable"
• If no tools found for server: Include server with toolCount = 0

Step 4: Scan Current Repository

Objective: Discover local resources inside the repository where the user is currently working.

Scope:

Scan from current working directory (repository root when available). Do not use hardcoded absolute paths.

4.1 Discover Local Agents:

Search for agent manifests in common conventions:

• **/plugin.json files containing agents arrays
• **/agents/*.md and **/agents/*.json
• **/.claude/agents/* and similar platform-local agent folders

For each candidate:

• Parse safely (JSON/YAML/Markdown metadata)
• Extract agent name, description, and source path
• Mark resource scope as local

4.2 Discover Local Skills:

Search for skill definitions in common conventions:

• **/skills/*/SKILL.md
• **/.*/skills/*/SKILL.md (hidden platform folders in repo)

Parse YAML frontmatter using same validation rules as installed skills.

4.3 Discover Local MCP Configurations:

Search for MCP configuration files in common conventions:

• ./.mcp.json
• ./mcp.json
• ./.config/mcp.json
• **/.mcp.json (nested workspace folders)

If multiple files exist:

• Parse all valid configs
• Merge by server name
• Deduplicate with installed scope by server name + command

4.4 Deduplication Rules:

• Keep installed and local inventories in separate sections
• Inside each section, deduplicate by normalized name
• If same resource appears in both scopes, keep both entries and label scope explicitly

Graceful Handling:

• If repository has no local resources: Return empty local arrays
• If a local file is malformed: Skip file, continue scan
• If repository root cannot be determined: Fallback to current working directory

Step 5: Apply Filters (Optional)

Objective: Filter results based on user-specified criteria.

Filter Types:

5.1 By Resource Type:

# 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 By Category:

# 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 By Keyword Search:

Filter by keyword: match the search term (case-insensitive substring) against plugin names, skill names and descriptions, trigger phrases, MCP server names, and tool names. Return only matching entries.

Filter Detection:

Detect filter intent from user request:

• "only", "just", "show me" → Type filter
• "related to", "about", "for" → Keyword search
• Category names (development, content, analysis) → Category filter

Step 6: Generate Catalog

Objective: Present discovered resources in clean, structured markdown.

Output Format:

# 📦 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