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
- 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-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
Anti-Patterns
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.
1---2name: api-for-yourself3description: Publish 'how to work with me' as a literal API spec — endpoints (what to ask me for and what you'll get back), rate limits (meeting and interrupt tolerance), error codes (what happens when you surprise me Friday 5pm), auth (how to earn trust), and a changelog. Use when onboarding to a new team, when a new manager or report arrives, for a team working-styles session, or 'write my README/user manual'. Produces a personal API spec that's genuinely funny and secretly the best onboarding doc on the team.4---5
6# API For Yourself Skill
7
8"User manual for me" documents have existed for years and mostly read like
9horoscopes ("I value transparency"). The API-spec format fixes them by force:
10an endpoint must say what you send and what comes back; a rate limit must be a
11number; an error code must name the actual failure behaviour. The joke is the
12format — the payload is real self-knowledge, and the test of every line is
13*would a new teammate behave differently after reading it?* Deadpan technical
14voice, honest contents, one page.
15
16## What This Skill Produces
17
18- A **personal API spec**: endpoints, request formats, rate limits, error
19 codes, auth & scopes, dependencies, scheduled maintenance, changelog —
20 in deadpan OpenAPI-ish style
21- A **quickstart** at the top: the three calls that cover 90% of integrations
22 with this human
23- Optionally a **team version**: specs for a whole team session, plus the
24 facilitation note for running it as an exercise
25
26## Required Inputs
27
28Ask for (if not already provided):
29- How people should bring them things: channel preferences, context depth
30 (one-liner or brief?), and what makes a request instantly workable vs
31 instantly annoying
32- Real capacity: meeting tolerance per day, focus blocks, response-time honest
33 averages by channel
34- Actual failure modes, told honestly: what happens when they're surprised
35 late Friday, overloaded, given vague asks, or micromanaged
36- What earns trust and what burns it; energy sources and drains; current
37 quirks a teammate would discover in week three anyway
38
39## Process
40
411. **Interview past the horoscope.** For every generic answer ("I like
42 directness"), push for the behavioural version: what does a *well-formed
43 request* actually contain? What's the observable symptom when it's
44 missing? The spec is built from behaviours, not values.
452. **Design the endpoints** — the 4–6 things people actually come to this
46 person for. Each gets: method + path (`POST /decisions`), request body
47 (what to include), response (what they'll get and by when), and the errors
48 it can throw. Include one honest deprecated endpoint (`/status-meetings —
49 deprecated, use async /updates instead`).
503. **Publish real numbers.** Rate limits with actual figures ("3 meetings/day
51 before response quality degrades — 429 after that"), response-time SLAs by
52 channel that match reality, scheduled maintenance (focus blocks, the school
53 run, timezone). A limit without a number is a mood.
544. **Write error codes as self-knowledge.** The funniest section and the most
55 useful: `429 Too Many Meetings` (symptom: monosyllabic replies; retry:
56 tomorrow morning) · `400 Vague Request` (returns clarifying questions, not
57 work) · `503 Friday 5pm Surprise` (accepted but not processed until Monday;
58 don't resend). Each code: symptom, what NOT to do, the retry strategy.
595. **Auth, changelog, quickstart.** Auth: how trust levels are earned and what
60 each unlocks (scope: `direct-feedback` granted after…). Changelog: 2–3
61 honest entries ("v3.1: no longer needs to win every argument — patched
62 after 2024 retro"). Quickstart on top: the three most-used calls, copy-paste
63 ready.
64
65## Output Format
66
67```
68# [Name] API — v[X.Y]
69> One-line summary of what this human is for.
70
71## Quickstart
72[The 3 calls covering 90% of use]
73
74## Endpoints
75### POST /[thing]
76Request: … · Response (SLA): … · Errors: [codes]
77
78## Rate limits
79[Real numbers: meetings, interrupts, context switches]
80
81## Error codes
82| Code | Trigger | Symptom you'll observe | Retry strategy |
83
84## Auth & scopes
85[How trust is earned; what each level unlocks]
86
87## Scheduled maintenance
88[Focus blocks, hours, timezone truths]
89
90## Changelog
91[2-3 honest entries — growth as version notes]
92```
93
94## Quality Checks
95
96- [ ] Every line passes the behaviour test: a new teammate would act
97 differently having read it — zero horoscope lines survive
98- [ ] Rate limits and SLAs carry real numbers the person will actually honour
99- [ ] At least one error code and one changelog entry required genuine honesty
100 (a flaw admitted, a patch noted) — that's what makes readers trust the
101 rest
102- [ ] The joke never outruns the information: deadpan format, true payload
103- [ ] One page; the quickstart works standalone if that's all anyone reads
104
105## Anti-Patterns
106
107- [ ] Do not write requirements-for-others disguised as self-documentation —
108 it's an API you offer, not an SLA you impose; tone stays "here's how to
109 get the best out of me"
110- [ ] Do not fake quirks for comedy or hide real ones for image — week three
111 reveals everything anyway
112- [ ] Do not ship without the errors section; specs with only happy paths are
113 marketing
114- [ ] Do not let it ossify — the changelog implies maintenance; suggest a
115 re-version at role changes
116
117## Related
118
119[[the-understudy]] is how an AI learns your inside; this is how humans call
120your outside. [[working-agreements]] for the team-level contract;
121[[onboarding-plan]] to slot this into a new joiner's week one.
Mohit Aggarwal