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.

1. 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`).

1. 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.

1. 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.

1. 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.

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.