Patterns for writing clear, consistent API field descriptions including types, constraints, examples, and edge cases.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
name: api-field-descriptions description: | Patterns for writing clear, consistent API field descriptions including types, constraints, examples, and edge cases.
trigger: |
skip_when: |
Field descriptions are the most-read part of API documentation. Users scan for specific fields and need clear, consistent information.
Every field description answers: What is it? (purpose), What type? (data type), Required? (mandatory), Constraints? (limits/validations), Example? (valid data)
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | uuid | — | The unique identifier of the Account |
| name | string | Yes | The display name of the Account (max 255 chars) |
| status | enum | — | Account status: `ACTIVE`, `INACTIVE`, `BLOCKED` |
Note: Use — for response-only fields (not applicable for requests).
For nested objects: status.code, status.description
| Type | Pattern | Example |
|---|---|---|
| UUID | "The unique identifier of the [Entity]" | id: uuid — The unique identifier of the Account |
| String | "[Purpose] (constraints)" | code: string — The asset code (max 10 chars, uppercase, e.g., "BRL") |
| String (format) | "[Purpose] (format example)" | email: string — Email address (e.g., "user@example.com") |
| Enum | "[Purpose]: val1, val2, val3" | type: enum — Asset type: \currency`, `crypto`, `commodity`` |
| Boolean | "If true, [what happens]. Default: [value]" | allowSending: boolean — If \true`, sending permitted. Default: `true`` |
| Integer | "[Purpose] (range)" | scale: integer — Decimal places (0-18) |
| Timestamp | "Timestamp of [event] (UTC)" | createdAt: timestamptz — Timestamp of creation (UTC) |
| Object (jsonb) | "[Purpose] including [fields]" | status: jsonb — Status information including code and description |
| Array | "List of [what it contains]" | operations: array — List of operations in the transaction |
In Requests:
Yes = Must be providedNo = OptionalConditional = Required in specific scenarios (explain in description)In Responses: Use — (response fields are always returned or null)
| Pattern | Format |
|---|---|
| Default values | "Results per page. Default: 10" |
| Nullable fields | "Soft deletion timestamp, or null if not deleted" |
| Deprecated fields | "[Deprecated] Use route instead" |
| Read-only fields | "Read-only. Generated by the system" |
| Relationships | "References an Asset code. Must exist in the Ledger" |
| Don't | Do |
|---|---|
| "The name" | "The display name of the Account" |
| "Status info" | "Account status: ACTIVE, INACTIVE, BLOCKED" |
| "A number" | "Balance version, incremented with each transaction" |
| "The code" | "The asset code (max 10 chars, uppercase)" |
| "The timestamp" | "Timestamp of creation (UTC)" |