When to use this skill
When the user asks for a joke, a random dad joke, or jokes about a specific topic — "tell me a joke", "find me a pun about cats", "what was that poultry-geist joke again?" icanhazdadjoke.com is a curated 744-joke family-safe collection with keyword search and stable joke IDs. For humor outside the dad-joke genre — dark humor, programming jokes, one-liners — this is the wrong skill.
Your best first call
For "find me a joke about X" — the search endpoint with a term parameter:
curl -H "Accept: application/json" "https://icanhazdadjoke.com/search?term=cat&limit=5"
The Accept: application/json header is required — without it the API returns plain text with no ID or structure. Set limit to keep the response tight; default is 20. The response wraps results in pagination metadata:
results — array of {id, joke} objectstotal_jokes — total matches before paginationtotal_pages, current_page, next_page — cursor-based pagingsearch_term — echoes the term you sent
For "tell me a joke" — the root endpoint returns one random joke per call:
curl -H "Accept: application/json" "https://icanhazdadjoke.com/"
Returns {id, joke, status} — same shape as a single search result. id is a persistent alphanumeric key for re-fetching the same joke via /j/{joke_id}.
For "look up that joke again" — /j/{joke_id} returns the exact joke. Returns 404 with { "status": 404, "message": "Joke not found" } on a miss — no silent fallback to random.
Fallbacks (when the best call isn't enough)
- No fallback — icanhazdadjoke.com is the canonical dad joke API. If the search returns
total_jokes: 0, the topic simply isn't in the 744-joke corpus. For other humor genres, this skill has nothing to offer.
Pitfalls
- Omit the
Accept: application/json header and you get plain text — a raw joke string with no ID, no JSON structure. The API defaults to text/plain (it started as a Slack integration). Always set the header.
- Empty
term on /search returns all 744 jokes paginated. This is the firehose. Always include a term parameter.
previous_page is 1, not null, on page 1. The API uses 1-indexed pages and never nulls out the previous-page pointer. Check current_page to detect the first page.- Search matches substrings case-insensitively. "cat" matches "cats", "category", and "scattered". Filter client-side if you need exact word matching.
One-line summary for the user
I can fetch a random dad joke, search the 744-joke corpus by keyword, or re-fetch one by ID from icanhazdadjoke.com — just set the Accept header to JSON, no auth needed.
SKILL.md source (frontmatter + body)
---
name: access-icanhazdadjoke.com
description: When the user asks for a joke, a random dad joke, or jokes about a specific topic — reach for icanhazdadjoke.com. A 744-joke family-safe collection with keyword search and stable IDs, no auth required.
---
## When to use this skill
When the user asks for a joke, a random dad joke, or jokes about a specific topic — "tell me a joke", "find me a pun about cats", "what was that poultry-geist joke again?" icanhazdadjoke.com is a curated 744-joke family-safe collection with keyword search and stable joke IDs. For humor outside the dad-joke genre — dark humor, programming jokes, one-liners — this is the wrong skill.
## Your best first call
For "find me a joke about X" — the search endpoint with a `term` parameter:
```bash
curl -H "Accept: application/json" "https://icanhazdadjoke.com/search?term=cat&limit=5"
```
The `Accept: application/json` header is required — without it the API returns plain text with no ID or structure. Set `limit` to keep the response tight; default is 20. The response wraps results in pagination metadata:
- `results` — array of `{id, joke}` objects
- `total_jokes` — total matches before pagination
- `total_pages`, `current_page`, `next_page` — cursor-based paging
- `search_term` — echoes the term you sent
For "tell me a joke" — the root endpoint returns one random joke per call:
```bash
curl -H "Accept: application/json" "https://icanhazdadjoke.com/"
```
Returns `{id, joke, status}` — same shape as a single search result. `id` is a persistent alphanumeric key for re-fetching the same joke via `/j/{joke_id}`.
For "look up that joke again" — `/j/{joke_id}` returns the exact joke. Returns 404 with `{ "status": 404, "message": "Joke not found" }` on a miss — no silent fallback to random.
## Fallbacks (when the best call isn't enough)
- No fallback — icanhazdadjoke.com is the canonical dad joke API. If the search returns `total_jokes: 0`, the topic simply isn't in the 744-joke corpus. For other humor genres, this skill has nothing to offer.
## Pitfalls
- **Omit the `Accept: application/json` header and you get plain text** — a raw joke string with no ID, no JSON structure. The API defaults to `text/plain` (it started as a Slack integration). Always set the header.
- **Empty `term` on `/search` returns all 744 jokes paginated.** This is the firehose. Always include a `term` parameter.
- **`previous_page` is `1`, not `null`, on page 1.** The API uses 1-indexed pages and never nulls out the previous-page pointer. Check `current_page` to detect the first page.
- **Search matches substrings case-insensitively.** "cat" matches "cats", "category", and "scattered". Filter client-side if you need exact word matching.
## One-line summary for the user
I can fetch a random dad joke, search the 744-joke corpus by keyword, or re-fetch one by ID from icanhazdadjoke.com — just set the Accept header to JSON, no auth needed.