api-for-yourself

API For Yourself Skill

"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

1. 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.
2. 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).
3. 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.
4. 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.
5. Auth, changelog, quickstart. Auth: how trust levels are earned and what each unlocks (scope: direct-feedback granted 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.