find-skills

# Find Skills

This skill helps you discover and install skills from the open agent skills ecosystem.

## CRITICAL RULES

1. **ALWAYS search first**: When a user asks to install/find/add ANY skill, your FIRST action must be running `skills find <query>` in the sandbox.
2. **NEVER create from scratch without searching**: Even for simple-sounding skills like "hello-world", search first.
3. **Use the CLI directly**: The `skills` CLI is pre-installed globally in the sandbox. Use `skills` directly (NOT `npx skills` — npx causes unnecessary download prompts).
4. **Install to session workspace**: Use `HOME=<workspace_dir> skills add ... -g -y --agent '*'` so skills land in the current session's workspace (visible in the task file viewer).
5. **Call propose_skill_save**: After installing and testing a skill, ALWAYS call the `propose_skill_save` tool with the skill name so the user can choose to save it permanently.

## When to Use This Skill

Use this skill when the user:

- Asks to **install** a skill (e.g., "install hello-world skill", "安装一个 skill")
- Asks to **find** or **search** for a skill (e.g., "find a skill for X", "找一个 skill")
- Mentions a skill **by name** (e.g., "hello-world skill", "react testing skill")
- Asks "how do I do X" where X might be a common task with 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

## What is the Skills CLI?

The Skills CLI (`skills`) is pre-installed globally in the sandbox. It is the package manager for the open agent skills ecosystem.

**IMPORTANT: Always use `skills` directly, NEVER use `npx skills` (npx will try to re-download and prompt for confirmation).**

**Key commands:**

- `skills find [query]` - Search for skills by keyword (use this FIRST)
- `HOME=<workspace_dir> skills add <package> -g -y --agent '*'` - Install a skill to session workspace
- `skills list -g` - List installed skills
- `skills check` - Check for skill updates

**Browse skills at:** https://skills.sh/

## How to Help Users Find Skills

### Step 1: Check Locally Installed Skills FIRST

Before searching the online ecosystem, check if a matching skill is **already installed locally**. Locally installed skills are listed in your system prompt under "Available Skills" and live at `/skills/<name>/SKILL.md`.

- If the user mentions a skill by name (e.g., "hello-world") and it appears in your available skills list → **use it directly**. Read its SKILL.md for instructions. No need to search online.
- If the user wants to **modify** an existing local skill → skip find-skills entirely and go to **skill-creator** (phase 2 in the Skill Policy).
- Only proceed to Step 2 if no local skill matches.

### Step 2: Understand What They Need

When no local skill matches, identify:

1. The domain (e.g., React, testing, design, deployment)
2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
3. Whether this is a common enough task that a skill likely exists

### Step 3: Search the Online Ecosystem

Run the find command with a relevant query:

```bash
skills find [query]
```

For example:

- User asks "how do I make my React app faster?" → `skills find react performance`
- User asks "can you help me with PR reviews?" → `skills find pr review`
- User asks "I need to create a changelog" → `skills find changelog`

The command will return results like:

```
Install with skills add <owner/repo@skill>

vercel-labs/agent-skills@vercel-react-best-practices
└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
```

### Step 4: Present Options to the User

When you find relevant skills, present them to the user with:

1. The skill name and what it does
2. The install command they can run
3. A link to learn more at skills.sh

Example response:

```
I found a skill that might help! The "vercel-react-best-practices" skill provides
React and Next.js performance optimization guidelines from Vercel Engineering.

To install it:
skills add vercel-labs/agent-skills@vercel-react-best-practices

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

### Step 5: Install to Session Workspace

If the user wants to proceed, install the skill into the **session workspace** so it appears in the task file viewer. Use `HOME=<workspace_dir>` to redirect the global install path:

```bash
HOME=<workspace_dir> skills add <owner/repo@skill> -g -y --agent '*'
```

Replace `<workspace_dir>` with your actual workspace directory (from the system prompt).

- `HOME=<workspace_dir>` — redirects `-g` install to `<workspace_dir>/.agents/skills/`
- `-g` installs globally (user-level, relative to HOME)
- `-y` skips confirmation prompts
- `--agent '*'` skips the interactive agent selection (REQUIRED in sandbox)

**IMPORTANT:** Never omit any of these flags. Without `--agent '*'` the command will hang waiting for interactive input.

### Step 6: Test the Installed Skill

After installation, test the skill by reading its SKILL.md/TEMPLATE.md and following its instructions.

- **If it works** → call `propose_skill_save(skill_name="<skill-name>")` to let the user save it permanently. Done!
- **If it does NOT fit the user's needs** → **do NOT keep trying to fix or adapt it**. Uninstall it and go back to Step 4 to try the **next candidate** from the search results.

### Step 7: Bail-Out — When to Stop Searching

Stop searching and escalate to **skill-creator** (create from scratch) when ANY of these is true:

1. **No results**: `skills find` returned zero matches.
2. **Exhausted candidates**: You have tried 2–3 different skills and none fit.
3. **Poor relevance**: All search results are clearly unrelated to what the user needs.

When bailing out:
1. Briefly tell the user: "I couldn't find a suitable existing skill. I'll create one from scratch."
2. Read `/builtin-skills/skill-creator/SKI