ReddRadar
Agent skill
api-field-descriptions
Patterns for writing clear, consistent API field descriptions including types, constraints, examples, and edge cases.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/api-field-descriptions
SKILL.md
API Field Descriptions
Field descriptions are the most-read part of API documentation. Users scan for specific fields and need clear, consistent information.
Field Description Structure
Every field description answers: What is it? (purpose), What type? (data type), Required? (mandatory), Constraints? (limits/validations), Example? (valid data)
Table Format (Preferred)
| 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
Description Patterns by Type
| 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 |
Required vs Optional
In Requests:
Yes= Must be providedNo= OptionalConditional= Required in specific scenarios (explain in description)
In Responses: Use — (response fields are always returned or null)
Special Field Documentation
| 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" |
Writing Good Descriptions
| 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)" |
Quality Checklist
- Description explains the field's purpose
- Data type is accurate
- Required/optional status is clear
- Constraints documented (max length, valid values)
- Default value noted (if optional)
- Nullable behavior explained (if applicable)
- Deprecated fields marked
- Read-only fields indicated
- Relationships to other entities clear
- Example values realistic
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?