Find Skills

Find Skills

Overview

Searches the open agent skills ecosystem and installs matching skills via the Skills CLI (pnpm dlx skills). Includes an enrichment script that fetches descriptions from skills.sh for each result, giving users context beyond raw skill names.

When to use: User asks for help with a domain that might have existing skills, wants to browse available skills, or asks to extend agent capabilities.

When NOT to use: User already knows the exact skill and install command, or the task has nothing to do with skill discovery.

Quick Reference

Common Skill Categories

Common Mistakes

Delegation

• Skill search execution: Run pnpm dlx skills find or the enrichment script directly
• Skill installation: Run pnpm dlx skills add after user confirms
• Detailed skill info: Browse the skill page on skills.sh before recommending

If the skill-management skill is available, delegate skill creation, auditing, and validation to it.

Otherwise, recommend: pnpm dlx skills add oakoss/agent-skills -s skill-management -a claude-code -y

If no matching skill is found, offer to help directly and suggest pnpm dlx skills init to create a custom skill.

References

• Discovery workflow and search strategies
• Enriched search script usage and options
• Installing skills from private repositories

Discovery Guide

When to Activate

Activate skill discovery when the user:

• Asks "how do I do X" where X might have an existing skill
• Says "find a skill for X" or "is there a skill for X"
• Asks "can you do X" where X is a specialized capability
• Expresses interest in extending agent capabilities
• Wants to search for tools, templates, or workflows
• Mentions they wish they had help with a specific domain

Step-by-Step Workflow

Step 1: Understand What They Need

Identify three things before searching:

1. The domain — React, testing, design, deployment, etc. 2. The specific task — writing tests, creating animations, reviewing PRs 3. Likelihood a skill exists — common tasks in popular domains usually have skills

Step 2: Search for Skills

Run the find command with a relevant query:

pnpm dlx skills find [query]

Example mappings from user requests to search queries:

For richer results with descriptions, use the enrichment script:

node scripts/enrich_find.js "react performance"

Step 3: Present Options to the User

When results are found, present each skill with:

1. The skill name and what it does 2. The install command (defaulting to Claude Code as the target agent) 3. A link to learn more on skills.sh

Example response format:

I found a skill that might help! The "react-best-practices" skill provides
React performance optimization guidelines.

To install it:
pnpm dlx skills add vercel-labs/agent-skills -s react-best-practices -a claude-code -y

Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices

Step 4: Offer to Install

If the user wants to proceed, install with confirmation bypass. Default to Claude Code as the target agent:

pnpm dlx skills add <source> -s <name> -a claude-code -y

For global (user-level) install:

pnpm dlx skills add <source> -s <name> -a claude-code -g -y

• -a claude-code targets Claude Code specifically
• -g installs at user level (available across projects)
• -y skips interactive confirmation

Agent Targeting

The -a flag controls which agent(s) receive the skill. Always specify the target agent explicitly.

Default agent: claude-code

To install for multiple agents, pass multiple names:

pnpm dlx skills add <source> -s <name> -a claude-code opencode github-copilot -y

To install for all detected agents:

pnpm dlx skills add <source> -s <name> -a '*' -y

Common agent identifiers (full list at github.com/vercel-labs/skills):

CLI Reference

Commands

Add Options

Remove Options

List Options

Source Formats

The <source> argument accepts multiple formats:

Search Tips

1. Use specific keywords — "react testing" beats just "testing" 2. Try alternative terms — if "deploy" returns nothing, try "deployment" or "ci-cd" 3. Check popular sources — many skills come from vercel-labs/agent-skills or oakoss/agent-skills 4. Browse the catalog — https://skills.sh/ shows curated listings 5. Combine domain + task — "typescript validation", "nextjs auth", "react forms" 6. Preview before installing — use --list to see available skills in a repo

When No Skills Are Found

If no relevant skills exist:

1. Acknowledge that no existing skill was found 2. Offer to help with the task directly using general capabilities 3. Suggest creating a custom skill if the task is recurring

I searched for skills related to "xyz" but didn't find any matches.
I can still help you with this task directly. Would you like me to proceed?

If this is something you do often, you could create your own skill:
pnpm dlx skills init my-xyz-skill

Skill Sources

Skills follow the Agent Skills open standard and work across 27+ agents including Claude Code, Cursor, Gemini CLI, and others.

Enriched Search

What It Does

The enrich_find.js script wraps pnpm dlx skills find and enriches each result with a human-readable description fetched from skills.sh. This gives users context about what each skill does without having to visit every page manually.

How It Works

The script operates in three steps:

1. Search — Runs pnpm dlx skills find <query> and parses the output 2. Fetch — For each result, fetches the skills.sh page and extracts descriptive text 3. Display — Presents results with name, URL, and description in a formatted layout

Usage

node scripts/enrich_find.js "<query>"

Options

Examples

# Basic search
node scripts/enrich_find.js "react"

# Limit to 5 results
node scripts/enrich_find.js "testing" --max 5

# Fast mode — skip description fetching
node scripts/enrich_find.js "deploy" --no-fetch

# Increase timeout for slow connections
node scripts/enrich_find.js "kubernetes" --timeout 20

# Single-threaded fetching
node scripts/enrich_find.js "auth" --concurrency 1

Output Format

Each result is displayed as:

owner/repo@skill
└ https://skills.sh/owner/repo/skill
description text from the skill page

With ANSI formatting:

• Bold — skill name
• Blue — URL
• Gray — description

When no results are found, outputs: No skills found.

Description Sources

The script tries two sources for descriptions, in order:

1. skills.sh — Extracts the first <p> tag from the prose section, or falls back to the <meta name="description"> tag 2. agent-skills.md — If skills.sh has no description, tries the equivalent page on agent-skills.md

If neither source provides a description, displays [no description found].

Requirements

• Node.js — Uses built-in https and child_process modules (no npm dependencies)
• Network access — Fetches from skills.sh and agent-skills.md
• Skills CLI — pnpm dlx skills must be available (installed on demand via pnpm)

Error Handling

• Network timeouts are handled per-request without failing the entire batch
• HTTP errors (4xx, 5xx) fall through to the fallback source
• Redirect chains are followed up to 3 hops
• If the skills CLI is not available, the script exits with a non-zero status
• Invalid options produce a usage error message

Private Repositories

The Problem

The owner/repo shorthand converts to an HTTPS URL internally. For private repos, this triggers the system credential helper, which often results in an endless spinner (the git credential prompt is hidden) or a "Repository not found" error.

Recommended: Use SSH URLs

The most reliable method for private repos is passing an SSH URL directly:

# GitHub private repo — install for Claude Code
pnpm dlx skills add git@github.com:YourOrg/private-skills.git -a claude-code -y

# GitHub private repo — specific skill
pnpm dlx skills add git@github.com:YourOrg/private-skills.git -s my-skill -a claude-code -y

# GitHub private repo — global install
pnpm dlx skills add git@github.com:YourOrg/private-skills.git -s my-skill -a claude-code -g -y

# GitLab private repo
pnpm dlx skills add git@gitlab.com:YourOrg/private-skills.git -a claude-code -y

# Multiple agents at once
pnpm dlx skills add git@github.com:YourOrg/private-skills.git -s my-skill -a claude-code opencode github-copilot -y

# List available skills in a private repo
pnpm dlx skills add git@github.com:YourOrg/private-skills.git --list

This works because SSH uses existing key-based authentication rather than HTTPS credentials.

Prerequisites

The user must have SSH keys configured for their git host:

# Verify SSH access to GitHub
ssh -T git@github.com

# Verify SSH access to GitLab
ssh -T git@gitlab.com

If SSH is not configured, the user needs to set up an SSH key and add it to their git host account.

Alternative: Configure HTTPS Credentials

If SSH is not available, pre-configure git credentials before running the skills CLI:

# Option 1: Use gh CLI (recommended if available)
gh auth setup-git

# Option 2: Store a personal access token
git config --global credential.helper store
# Then authenticate once — credentials are cached for future use

After configuring credentials, the owner/repo shorthand works normally:

pnpm dlx skills add YourOrg/private-skills -s my-skill -a claude-code -y

Known Limitations

skills check and skills update Do Not Work

The CLI makes unauthenticated GitHub API calls to detect skill updates. For private repos, these return 404, so:

• pnpm dlx skills check always shows "skipped (reinstall needed)"
• pnpm dlx skills update cannot update private repo skills

Workaround: Reinstall the skill to update it:

pnpm dlx skills add git@github.com:YourOrg/private-skills.git -s my-skill -a claude-code -y

Spinner Hides Credential Prompts

If the CLI appears stuck during "Cloning repository," it may be waiting for credential input hidden behind the spinner. Kill the process and retry with an SSH URL instead.

Troubleshooting