diff --git a/skills/search-issues/SKILL.md b/skills/search-issues/SKILL.md
index b056c0f..70478a3 100644
--- a/skills/search-issues/SKILL.md
+++ b/skills/search-issues/SKILL.md
@@ -171,6 +171,16 @@ Do NOT combine multiple searches into one shell command (e.g. with `&` and
 # Outputs are interleaved and unreadable.
 ```
 
+## Timeout setting and retry
+
+Since the script will scan all issues page by page, a large repo may take a long time.
+Thus, when initializing the tool call, you may specify a longer timeout like 10 minutes (600000ms).
+
+Also, there might be multiple agents trying to search through the issues at the same time,
+thus, a lot of request will be sent at the same time. The forgejo server may overload
+and failed to response the request, causing the script to crash. When this happens,
+sleep for several seconds and then retry the search.
+
 ## When to use this skill
 
 - You need to find specific tickets by keyword in a large repository.