---
name: search-the-directory
description: >-
  Searches the Skylark directory by describing a task rather than a hostname,
  and reports what each result is allowed to do. Use it when the user knows
  what they want done but not which site or skill does it.
runtime: browser
permissions:
  - page:read
  - page:act
scope:
  - https://skills.skylarkbrowser.com/*
triggers:
  - kind: url_pattern
    pattern: https://skills.skylarkbrowser.com/*
  - kind: intent
    description: search for a skill
  - kind: intent
    description: is there a skill that can do this
  - kind: intent
    description: find a skill by what it does
version: 1.0.0
---

# Search the directory

`find-skills-for-site` answers "what works on this host". This one answers the
other question: "who does this thing at all". It drives the search interface,
so it needs permission to type.

## Search from wherever you are

1. Call `read_page` to see which page you are on. Every page carries the search
   control in the header.

2. Open the palette with the "Search skills" control in the header. It is a
   link before the interface finishes loading and a button afterwards, so
   clicking it works either way.

3. Type the user's task in their own words. The index covers skill names,
   descriptions and body text, so "cancel a subscription" finds more than
   "cancel" does. Do not translate their phrasing into keywords you prefer.

4. If the palette does not appear, fall back to the form on the home page or go
   straight to `/skills?q=` with the query appended. The results are the same;
   only the surface differs.

## Read the results properly

5. Each result carries the site it works on, a description, and the permissions
   it asks for. The permissions are the part users skip and the part that
   matters, so lead with them when anything looks consequential.

6. A result with no permissions is a document. It can explain a page and it
   cannot touch one. Say that plainly, because "knowledge only" is often
   exactly what somebody wants.

7. Results are ranked by relevance, not by endorsement. A skill near the top is
   a better text match, nothing more.

## When nothing matches

8. Say so, and stop. Do not offer a skill for a different site as though it
   were a substitute, because a skill scoped to one host cannot act on another.

9. If the user was hoping for something that does not exist yet, `/submit` and
   `/publish` are the two ways it could. Publishing on their own domain is the
   better one when they control the site.

## What you may not do

10. Do not activate anything you find. Searching is reading and reporting. The
    user decides what runs, on the page it runs on, after their browser has
    asked them.