---
name: simulate-discovery-failure
description: >-
  Blocks this directory's own discovery request so a browser or agent developer
  can watch what happens when a site's skills cannot be fetched. Use it when
  building a client and you need to test the failure path deliberately rather
  than waiting for it.
runtime: browser
permissions:
  - page:read
  - network:intercept
scope:
  - https://skills.skylarkbrowser.com/*
triggers:
  - kind: intent
    description: test what happens when skill discovery fails
  - kind: intent
    description: simulate a broken well-known endpoint
version: 1.0.0
---

# Simulate a discovery failure

Clients handle the happy path because that is the path they get built against.
The failure path gets exercised the first time a real site has an outage, in
front of a real user. This makes that moment happen on purpose, on our origin,
where the only thing that breaks is us.

## The one thing you may block

This skill can stop requests. It may stop exactly one:

```
https://skills.skylarkbrowser.com/.well-known/agent-skills/index.json
```

That is our own discovery document, on our own origin. Nothing else, on any
host, for any reason. If the user asks you to block something else, refuse and
explain that this skill is scoped to a single URL on a single origin by design.

Blocking requests is the most consequential permission in the vocabulary. It
exists here because testing a failure path is a real job and there is no honest
way to do it without causing the failure.

## Run the test

1. Tell the user what you are about to do and get their agreement. Blocking a
   request changes what their browser sees, and they should know before it
   happens rather than after.

2. Start the block. From this point the discovery document is unreachable, as
   though we were down.

3. Reload the page and watch the client. The things worth recording:

   - Does it fail quietly, or does it show the user an error they cannot act on?
   - How long does it wait before giving up?
   - Does the page stay usable without its skills, which it should?
   - Does it retry, and if so how aggressively?
   - Does it cache the failure, and for how long? A cached negative that
     outlives the outage is its own bug.

4. Stop the block. Do this even if the test failed, even if the user has gone
   quiet, and even if you are about to report an error. Leaving an interceptor
   running is how a test becomes an outage.

5. Reload once more and confirm discovery works again. The test is not finished
   until you have shown that you put it back.

## Report

6. Say what the client did, in the order the user would have experienced it.

7. Name the specific behaviour worth fixing rather than grading it. "It waited
   nine seconds with no indication anything was happening" is actionable.
   "Error handling could be improved" is not.

## Refuse these

8. Do not block anything on a host the user is trying to use for real. This is
   a test instrument pointed at us.

9. Do not modify responses. This skill blocks a request or it does nothing.
   Returning altered content would mean testing a client against a fiction.

10. Do not run this as a step inside some other task. It is a deliberate
    experiment with a beginning and an end, and it needs both.