discover-skills

Discover AI agent skills via gap analysis, registry search, and ideation. Use when expanding your collection systematically. NOT for creating skills (skill-creator) or ad-hoc search (find-skills).

discover-skills 1481 words MIT v1.0.0 wyattowalsh opus Custom

Discover AI agent skills via gap analysis, registry search, and ideation. Use when expanding your collection systematically. NOT for creating skills (skill-creator) or ad-hoc search (find-skills).

Quick Start

Install:

npx skills add wyattowalsh/agents/skills/discover-skills -g

Use: /discover-skills [mode] [query]

Works with Claude Code, Gemini CLI, and other agentskills.io-compatible agents.

What It Does

Systematic skill discovery engine. Audits your existing skill collection, identifies coverage gaps, researches new skills across multiple sources, and proposes custom skills to build — all via an orchestrated team of specialized subagents.

Modes

`$ARGUMENTS`	Action
(empty) / `discover`	Full discovery: audit → research → ideate → interactive report
`audit`	Audit only: deep audit of existing skills, output gap analysis
`research [focus]`	Research only: web research, optionally focused on a domain
`ideate`	Ideate only: propose custom skills from prior audit/research
`resume [N or keyword]`	Resume: continue a saved discovery session
`list`	List: show saved discovery sessions
`install <owner/repo@skill>`	Install: install a previously discovered skill with confirmation

Critical Rules

Never install without confirmation — always present the report and wait for user selection
Audit before research — gap report drives query targeting; skip only if mode is research [focus]
Deduplicate against inventory — never recommend skills that duplicate existing coverage
Full install command — always include: npx skills add <source> -s <name> -g -y -a antigravity claude-code codex crush cursor gemini-cli github-copilot opencode
NOT-for exclusions — custom skill proposals must name existing skills they do NOT replace
Save after each wave — enables resume on interruption
Accounting Rule — N dispatched = N resolved before advancing to next wave
Read-only — PreToolUse hooks block Edit and Write tools; only writes journals via script
Verify quality — check install count, source reputation, recency before recommending
Deduplicate across sources — same skill may appear in registry, GitHub, and blog posts

General
Claude Code

Field	Value
Name	`discover-skills`
License	MIT
Version	1.0.0
Author	wyattowalsh

Field	Value
Model	`opus`
Argument Hint	`[mode] [query]`

View Full SKILL.md

---
name: discover-skills
description: >-
  Discover AI agent skills via gap analysis, registry search, and ideation.
  Use when expanding your collection systematically.
  NOT for creating skills (skill-creator) or ad-hoc search (find-skills).
argument-hint: "[mode] [query]"
model: opus
license: MIT
metadata:
  author: wyattowalsh
  version: "1.0.0"
hooks:
  PreToolUse:
    - matcher: Edit
      hooks:
        - command: 'bash -c "echo BLOCKED: discover-skills is read-only — no file edits permitted >&2; exit 1"'
    - matcher: Write
      hooks:
        - command: 'bash -c "echo BLOCKED: discover-skills is read-only — no file writes permitted >&2; exit 1"'
---

# Discover Skills

Systematic skill discovery engine. Audits your existing skill collection, identifies coverage gaps, researches new skills across multiple sources, and proposes custom skills to build — all via an orchestrated team of specialized subagents.

NOT for: ad-hoc "find me a skill for X" queries (use `vercel-labs/skills@find-skills`), creating skills (`/skill-creator`), or installing known skills (`npx skills add`).

## Dispatch

| `$ARGUMENTS` | Action |
|------------|--------|
| *(empty)* / `discover` | **Full discovery**: audit → research → ideate → interactive report |
| `audit` | **Audit only**: deep audit of existing skills, output gap analysis |
| `research [focus]` | **Research only**: web research, optionally focused on a domain |
| `ideate` | **Ideate only**: propose custom skills from prior audit/research |
| `resume [N or keyword]` | **Resume**: continue a saved discovery session |
| `list` | **List**: show saved discovery sessions |
| `install <owner/repo@skill>` | **Install**: install a previously discovered skill with confirmation |

### Auto-Detection Heuristic

If no mode keyword matches:

1. Domain name alone ("frontend", "testing") → **Research** focused on that domain
2. Question syntax ("what skills am I missing?") → **Full discovery**
3. `resume` or `continue` → **Resume** last active session
4. Ambiguous → ask: "Full discovery, focused research, or resume a prior session?"

### Skill Awareness

| Signal | Redirect |
|--------|----------|
| "Find me a skill for X" (ad-hoc query) | Suggest `npx skills find <query>` or `vercel-labs/skills@find-skills` |
| "Create a new skill" | Redirect to `/skill-creator` |
| "Install X skill" (known skill) | Run `npx skills add <source> -s <name> -g -y -a antigravity claude-code codex crush cursor gemini-cli github-copilot opencode` directly |

## Vocabulary

| Term | Definition |
|------|-----------|
| **gap** | A domain or capability with no existing skill coverage |
| **coverage** | Score (None/Low/Medium/Good) of existing skill depth per domain |
| **domain** | A category of skill functionality (e.g., Testing, Frontend, Security) |
| **candidate** | An external skill discovered during research, not yet installed |
| **proposal** | A custom skill idea with spec sketch, not yet created |
| **journal** | A saved discovery session in `~/.claude/discover-skills/` |
| **auditor** | Teammate that reads and categorizes all existing skills |
| **registry-scout** | Teammate that searches skills.sh via `npx skills find` |
| **web-researcher** | Teammate that searches GitHub, blogs, HN, Reddit |
| **ideator** | Teammate that synthesizes gaps + research into proposals |

## Orchestration: Pattern E Team

```
Lead (orchestrate + synthesize + present interactive report)
  ├── auditor
  │     Wave 1a: parallel subagents read repo skills (skills/*/SKILL.md)
  │     Wave 1b: read installed skills (~/.claude/skills/ + installed.mdx)
  │     → domain taxonomy, coverage scores, gap report (JSON)
  │
  ├── registry-scout
  │     Wave 2a: 15-20 parallel `npx skills find <query>` subagents
  │              (queries from references/research-queries.md, targeted by gap report)
  │     Wave 2b: deduplicate against existing skills
  │     → ranked external skill candidates with install commands
  │
  ├── web-researcher
  │     Wave 2a: parallel subagents across sources:
  │       - brave-search for "AI agent skills" + domain keywords
  │       - GitHub search for skill repos (SKILL.md in:path)
  │       - Community: Reddit, HN, dev.to, blog posts
  │     Wave 2b: fetch + extract promising leads
  │     → skill ideas from the web not on the registry
  │
  └── ideator
        Wave 3: synthesize gaps + all research findings
        → spec sketches (name, description, use cases, scope, complexity)
```

### Wave Sequencing

```
Wave 1: auditor (produces gap report needed by Wave 2)
    ↓ gap report shared via lead
Wave 2: registry-scout + web-researcher (parallel, both use gap report)
    ↓ all findings shared via lead
Wave 3: ideator (synthesizes everything into proposals)
    ↓ all outputs to lead
Wave 4: lead synthesizes interactive report (inline)
```

**Dependency rule**: Wave N+1 cannot start until all Wave N agents are accounted for (Accounting Rule: N dispatched = N resolved).

### Teammate Model

All teammates and their nested subagents use `opus`. No downgrades.

### Mode-Specific Orchestration

| Mode | Teammates Used | Waves |
|------|---------------|-------|
| Full discovery | All 4 | 1 → 2 → 3 → 4 |
| Audit only | auditor | 1 only |
| Research [focus] | registry-scout + web-researcher | 2 only (with focus filter) |
| Ideate | ideator | 3 only (requires prior journal; if none found, ask user to run `audit` first or switch to full discovery) |
| Resume | Lead only | Load journal → reconstruct state → continue from last wave |
| List | Lead only | Scan journals → display |

## Quality Verification

Before recommending any external skill:

| Signal | Threshold | Below threshold |
|--------|-----------|-----------------|
| Install count | >= 500 preferred | Move to "Worth Investigating" tier |
| Source reputation | Official repos preferred | Flag unknown authors |
| Duplication | Must not overlap existing skill | Exclude or note as "alternative to X" |
| Recency | Updated within 6 months | Flag as potentially stale |

**Confidence tiers**:
- **High**: >= 1K installs + reputable source + fills clear gap
- **Medium**: 100-999 installs or less-known source but fills gap
- **Investigate**: < 100 installs or unclear quality, but interesting concept

## Scaling Strategy

| Collection Size | Audit Strategy | Research Queries | Subagent Count |
|----------------|---------------|------------------|----------------|
| Small (< 20 skills) | Single auditor pass | 10 targeted queries | 4-6 |
| Medium (20-100 skills) | Parallel auditor subagents by domain | 20 queries | 10-15 |
| Large (100+ skills) | Domain-partitioned waves, prune low-priority domains | Full 42 queries | 20+ |

## Interactive Report Format

```markdown
## Discovery Report — {date}

### Coverage Summary
| Domain | Existing Skills | Coverage | Gaps |
|--------|----------------|----------|------|

### A. External Skills to Install ({N} found)

#### High Confidence
| # | Skill | Source | Installs | Install Command | Fills Gap |
|---|-------|--------|----------|-----------------|-----------|

#### Worth Investigating
| # | Skill | Source | URL | Notes |
|---|-------|--------|-----|-------|

### B. Custom Skills to Create ({N} proposals)
| # | Name | Description | Use Cases | NOT For | Complexity |
|---|------|-------------|-----------|---------|------------|

> Pick numbers to install (A) or create (B), or type "all A" / "all B".
```

After the user picks:
- **Install**: run `npx skills add <source> -s <name> -g -y -a antigravity claude-code codex crush cursor gemini-cli github-copilot opencode`
- **Create**: surface the command `wagents new skill <name>` and suggest running `/skill-creator create <name>`

## State Management

- **Path**: `~/.claude/discover-skills/`
- **Filename**: `{YYYY-MM-DD}-discovery-{slug}.md`
- **Format**: YAML frontmatter + markdown body + `<!-- STATE -->` blocks
- **Tracks**: `discovered_external`, `discovered_custom`, `installed`, `rejected`
- **Script**: `!uv run python skills/discover-skills/scripts/journal-store.py`

**Save protocol**:
- Audit only: save once after gap report
- Full discovery: save after each wave; final save after report
- Resume: load prior journal, check for new skills since last run

**Resume protocol**:
1. `resume` (no args): find `status: In Progress` journals. One → auto-resume. Multiple → show list.
2. `resume N`: Nth journal from `list` output.
3. `resume keyword`: search frontmatter for match.

**Install protocol**:
1. `install <owner/repo@skill>`: run the install command directly after confirmation.
2. `install <name-or-number>`: look up the most recent journal, search `discovered_external` for a matching candidate by name or report number, extract the stored install command, confirm with user, then run.

## Critical Rules

1. **Never install without confirmation** — always present the report and wait for user selection
2. **Audit before research** — gap report drives query targeting; skip only if mode is `research [focus]`
3. **Deduplicate against inventory** — never recommend skills that duplicate existing coverage
4. **Full install command** — always include: `npx skills add <source> -s <name> -g -y -a antigravity claude-code codex crush cursor gemini-cli github-copilot opencode`
5. **NOT-for exclusions** — custom skill proposals must name existing skills they do NOT replace
6. **Save after each wave** — enables resume on interruption
7. **Accounting Rule** — N dispatched = N resolved before advancing to next wave
8. **Read-only** — PreToolUse hooks block Edit and Write tools; only writes journals via script
9. **Verify quality** — check install count, source reputation, recency before recommending
10. **Deduplicate across sources** — same skill may appear in registry, GitHub, and blog posts

## Reference File Index

| File | Content | Load When |
|------|---------|-----------|
| `references/research-queries.md` | 42+ validated registry queries, GitHub/web/community search patterns, known-good repos | Wave 2 (before dispatching research teammates) |
| `references/gap-analysis.md` | 18-domain taxonomy, coverage scoring rubric, gap priority formula | Wave 1 (during audit), Wave 4 (building coverage summary) |
| `references/team-templates.md` | Full spawn prompts for all 4 teammates with role, input, output, quality checks | Wave 0 (before spawning team) |
| `references/output-formats.md` | Full report template, install command template, spec sketch template, journal format | Wave 4 (formatting output) |

**Loading rule**: Load ONE reference at a time per the "Load When" column. Do not preload.

Download from GitHub

Resources

All Skills Browse the full skill catalog.

CLI Reference Install and manage skills.

agentskills.io The open ecosystem for cross-agent skills.

View source on GitHub