api-and-interface-design
An agent skill by addyosmani, from addyosmani/agent-skills. Tags: api, design, documents, web.
What it does
Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.
Install
With the skills CLI, which installs into Claude Code, Codex, Cursor and other agents:
npx skills add addyosmani/agent-skills --skill api-and-interface-designOr copy the skill folder into Claude Code's skills directory by hand (~/.claude/skills for every project, or .claude/skills inside one):
git clone --depth 1 https://github.com/addyosmani/agent-skills
cp -r agent-skills/skills/api-and-interface-design ~/.claude/skills/api-and-interface-designSafety box score
Grade A, minimal risk: 0 of 100 risk points, rated 2026-09-22. The grade rates what the skill and its scripts can reach on the machine of whoever installs it, across eight categories from shell execution to secrets access. How the score works.
This skill is documentation-only: it provides API/interface design guidance in `SKILL.md` and ships no executable code, installers, or networked tooling. The main “risk” is not machine impact but that its conventions may shape how an agent designs interfaces, especially around idempotency, validation, and backward compatibility.
| Category | Level | Why |
|---|---|---|
| Code & shell execution | 0 (none) | No scripts, shell commands, or code execution paths are shipped; the only file is `SKILL.md`. |
| Network access | 0 (none) | The skill does not download data or send anything to remote hosts; it only describes API design practices. |
| Filesystem reach | 0 (none) | There are no reads, writes, or deletions outside the project because there is no runnable code at all. |
| Secrets & credentials | 0 (none) | It does not ask for tokens, passwords, `.env` files, or other credentials. |
| Privilege & persistence | 0 (none) | No sudo, global installs, services, or shell/OS configuration changes are present. |
| Instruction hijack surface | 0 (none) | `SKILL.md` contains design guidance only and does not tell the agent to ignore instructions, hide behavior, or follow remote content. |
| Irreversible actions | 0 (none) | It does not perform or instruct sending messages, deploying, paying, publishing, or deleting; it is advisory only. |
| Transparency | 0 (none) | Everything provided is plain text Markdown; there are no binaries, minified blobs, or runtime-generated code. |
Before installing
- Read `SKILL.md` to confirm its REST naming, pagination, and error-shape conventions match your team’s API standard.
- If you already enforce your own interface rules, compare them against this skill’s idempotency and backward-compatibility guidance before adopting it.
Rated 2026-09-22 by an automated review of 1 file from the skill's repository.
Source
- Repository
- addyosmani/agent-skills (all skills from this repository)
- Path
- skills/api-and-interface-design/SKILL.md
- Branch
- main
- Updated
- 2026-09-19
Related skills
- stitch::extract-static-html — Extract self-contained static HTML from a built web application or React components by inlining CSS and images.
- source-driven-development — Grounds every implementation decision in official documentation.
- archify — Create polished, validated architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as explorable standalone HTML with inline SVG.
- code-documenter — Generates, formats, and validates technical documentation — including docstrings, OpenAPI/Swagger specs, JSDoc annotations, doc portals, and user guides.
- customer-journey-map — Create an end-to-end customer journey map with stages, touchpoints, emotions, pain points, and opportunities.
- django-storages-s3 — Use when configuring Django to store static and media files on AWS S3 with django-storages.