"User manual for me" documents have existed for years and mostly read like horoscopes ("I value transparency"). The API-spec format fixes them by force: an endpoint must say what you send and what comes back; a rate limit must be a number; an error code must name the actual failure behaviour. The joke is the format — the payload is real self-knowledge, and the test of every line is would a new teammate behave differently after reading it? Deadpan technical voice, honest contents, one page.
What This Skill Produces
- A personal API spec: endpoints, request formats, rate limits, error codes, auth & scopes, dependencies, scheduled maintenance, changelog — in deadpan OpenAPI-ish style
- A quickstart at the top: the three calls that cover 90% of integrations with this human
- Optionally a team version: specs for a whole team session, plus the facilitation note for running it as an exercise
Required Inputs
Ask for (if not already provided):
- How people should bring them things: channel preferences, context depth (one-liner or brief?), and what makes a request instantly workable vs instantly annoying
- Real capacity: meeting tolerance per day, focus blocks, response-time honest averages by channel
- Actual failure modes, told honestly: what happens when they're surprised late Friday, overloaded, given vague asks, or micromanaged
- What earns trust and what burns it; energy sources and drains; current quirks a teammate would discover in week three anyway
Process
- Interview past the horoscope. For every generic answer ("I like directness"), push for the behavioural version: what does a well-formed request actually contain? What's the observable symptom when it's missing? The spec is built from behaviours, not values.
- Design the endpoints — the 4–6 things people actually come to this
person for. Each gets: method + path (
POST /decisions), request body (what to include), response (what they'll get and by when), and the errors it can throw. Include one honest deprecated endpoint (/status-meetings — deprecated, use async /updates instead). - Publish real numbers. Rate limits with actual figures ("3 meetings/day before response quality degrades — 429 after that"), response-time SLAs by channel that match reality, scheduled maintenance (focus blocks, the school run, timezone). A limit without a number is a mood.
- Write error codes as self-knowledge. The funniest section and the most
useful:
429 Too Many Meetings(symptom: monosyllabic replies; retry: tomorrow morning) ·400 Vague Request(returns clarifying questions, not work) ·503 Friday 5pm Surprise(accepted but not processed until Monday; don't resend). Each code: symptom, what NOT to do, the retry strategy. - Auth, changelog, quickstart. Auth: how trust levels are earned and what
each unlocks (scope:
direct-feedbackgranted after…). Changelog: 2–3 honest entries ("v3.1: no longer needs to win every argument — patched after 2024 retro"). Quickstart on top: the three most-used calls, copy-paste ready.
Output Format
# [Name] API — v[X.Y]
> One-line summary of what this human is for.
## Quickstart
[The 3 calls covering 90% of use]
## Endpoints
### POST /[thing]
Request: … · Response (SLA): … · Errors: [codes]
## Rate limits
[Real numbers: meetings, interrupts, context switches]
## Error codes
| Code | Trigger | Symptom you'll observe | Retry strategy |
## Auth & scopes
[How trust is earned; what each level unlocks]
## Scheduled maintenance
[Focus blocks, hours, timezone truths]
## Changelog
[2-3 honest entries — growth as version notes]
Quality Checks
- Every line passes the behaviour test: a new teammate would act differently having read it — zero horoscope lines survive
- Rate limits and SLAs carry real numbers the person will actually honour
- At least one error code and one changelog entry required genuine honesty (a flaw admitted, a patch noted) — that's what makes readers trust the rest
- The joke never outruns the information: deadpan format, true payload
- One page; the quickstart works standalone if that's all anyone reads
Anti-Patterns
- Do not write requirements-for-others disguised as self-documentation — it's an API you offer, not an SLA you impose; tone stays "here's how to get the best out of me"
- Do not fake quirks for comedy or hide real ones for image — week three reveals everything anyway
- Do not ship without the errors section; specs with only happy paths are marketing
- Do not let it ossify — the changelog implies maintenance; suggest a re-version at role changes
Related
[[the-understudy]] is how an AI learns your inside; this is how humans call your outside. [[working-agreements]] for the team-level contract; [[onboarding-plan]] to slot this into a new joiner's week one.