When to use this skill
When the user wants Chuck Norris jokes about a specific topic — a game, a sport, a movie, a programming concept, or any concrete noun phrase. This is the keyword-search path into chucknorris.io, not the random-joke path. For a single random joke with no topic, use /jokes/random directly instead. For browsing available themes before searching, call /jokes/categories first.
Your best first call
curl "https://api.chucknorris.io/jokes/search?query=mortal+kombat"
No auth. No key. Returns a JSON object with total (integer) and result (array of joke objects). Each joke object has id, value, categories, and url.
The total field is your decision hinge. When it's small (under ~10), return all of them or pick the best. When total is large — which happens with single common words like "the" or "can" — pick one from result at random and surface only that one. Do not dump a hundred jokes into the conversation.
Fallbacks (when the best call isn't enough)
- User wants a random joke, not a topic-specific one →
curl "https://api.chucknorris.io/jokes/random" returns one joke, no query needed. Add ?category=dev (or any of the 16 categories) to narrow by theme instead of keyword.
- User doesn't know what to search for →
curl "https://api.chucknorris.io/jokes/categories" returns the 16 named categories (dev, science, music, food, etc.) so the user can pick a theme.
Pitfalls
- Single common words return hundreds of results. A query like
query=the returns a total in the hundreds. Always check total before deciding how many jokes to surface — when it's large, pick one at random, don't list them all.
- The dataset is frozen. Every joke has a
created_at of 2020-01-05. No new jokes have been added since. Don't expect references to anything after 2020.
categories: [] is normal, not missing data. Most jokes are untagged. Only a minority carry a category label. Absence of categories does not mean the joke is broken.- Explicit jokes can match a search query. The
explicit category is not filtered out of search results. Check the categories field on each result before surfacing jokes to users who didn't ask for adult content.
One-line summary for the user
I can search Chuck Norris jokes by keyword via chucknorris.io — but use specific multi-word phrases, since single common words return hundreds of results.
SKILL.md source (frontmatter + body)
---
name: search-chuck-norris-jokes-by-keyword
description: When the user wants Chuck Norris jokes about a specific topic — a game, sport, movie, programming concept, or any concrete noun phrase — reach for the chucknorris.io keyword search. Unauthenticated GET, no key required.
---
## When to use this skill
When the user wants Chuck Norris jokes about a specific topic — a game, a sport, a movie, a programming concept, or any concrete noun phrase. This is the keyword-search path into chucknorris.io, not the random-joke path. For a single random joke with no topic, use `/jokes/random` directly instead. For browsing available themes before searching, call `/jokes/categories` first.
## Your best first call
```bash
curl "https://api.chucknorris.io/jokes/search?query=mortal+kombat"
```
No auth. No key. Returns a JSON object with `total` (integer) and `result` (array of joke objects). Each joke object has `id`, `value`, `categories`, and `url`.
The `total` field is your decision hinge. When it's small (under ~10), return all of them or pick the best. When `total` is large — which happens with single common words like "the" or "can" — pick one from `result` at random and surface only that one. Do not dump a hundred jokes into the conversation.
## Fallbacks (when the best call isn't enough)
- **User wants a random joke, not a topic-specific one** → `curl "https://api.chucknorris.io/jokes/random"` returns one joke, no query needed. Add `?category=dev` (or any of the 16 categories) to narrow by theme instead of keyword.
- **User doesn't know what to search for** → `curl "https://api.chucknorris.io/jokes/categories"` returns the 16 named categories (`dev`, `science`, `music`, `food`, etc.) so the user can pick a theme.
## Pitfalls
- **Single common words return hundreds of results.** A query like `query=the` returns a `total` in the hundreds. Always check `total` before deciding how many jokes to surface — when it's large, pick one at random, don't list them all.
- **The dataset is frozen.** Every joke has a `created_at` of `2020-01-05`. No new jokes have been added since. Don't expect references to anything after 2020.
- **`categories: []` is normal, not missing data.** Most jokes are untagged. Only a minority carry a category label. Absence of categories does not mean the joke is broken.
- **Explicit jokes can match a search query.** The `explicit` category is not filtered out of search results. Check the `categories` field on each result before surfacing jokes to users who didn't ask for adult content.
## One-line summary for the user
I can search Chuck Norris jokes by keyword via chucknorris.io — but use specific multi-word phrases, since single common words return hundreds of results.