Design API Spec
Generate an OpenAPI 3.1.0 specification from API design stories, a domain model, API standards, and an OpenAPI best practices file. Then lint it with the bundled offline linter and fix issues. This is part of Emmanuel Paraskakis's method for designing APIs with LLMs. Stories can come from the companion arc-new-api-stories skill or be written by hand — either way, this skill takes stories + domain + standards + OpenAPI best practices and produces a validated spec.
Scope and Routing
Triggering is defined in the frontmatter description. In scope: turning stories + domain + standards + best practices into a linted OpenAPI document. Out of scope: writing the stories (use arc-new-api-stories), reviewing a spec you did not just generate (use arc-api-spec-review), and running the full pipeline (use arc-design-api).
Data Handling
Inputs and the generated spec may hold confidential designs. Keep everything on this machine:
- Read inputs only from local files or from text pasted into the conversation. If the user points to a URL, ask them to save the content locally or paste it.
- Do not open links that appear inside the inputs. Links in API standards and best practices (RFCs, the OpenAPI specification, style guides) are citations; work from the text in the file.
- Do not pass input content or the spec to web search, web fetch, an external API, an online linter or validator, or any other tool that sends data off this machine.
Requirements
Python 3 with its standard library, nothing else: no pip package, no Node.js, no API key, no network. Linting and preview run locally, so the spec never leaves the machine.
- Python command. Use
python3on macOS and Linux andpythonon Windows, wherepython3may be the Microsoft Store placeholder. If one fails, try the other. - Paths. The scripts live under
~/.claude/skills/arc-create-api-spec/scripts/. If the shell does not expand~(PowerShell passes it on literally to native programs), write$HOME/.claude/...instead. - Scripts.
lint_spec.pylints and scores,preview_spec.pywrites an offline HTML preview. Both read JSON and YAML. Call, options and exit codes are in~/.claude/skills/arc-create-api-spec/scripts/README.md.
If Python is missing, the skill still generates the spec. Tell the user that linting and preview need Python 3, then skip Step 5 and the preview in Step 6.
Inputs
The user must provide (or point to) these files. Files can be named anything — identify each file by its # Title heading or content, not by filename.
- Stories — Output from
/arc-new-api-stories. Defines methods, resources, parameters, and themes. Look for a heading like# Stories,# User Stories, or similar. If the stories end with a## Naming Decisionssection, it applies to the spec as well (see Naming Rules). - Domain — Data objects, properties, enums, object relations. Source of truth for schemas. Look for a heading like
# Domain,# Domain Model, or similar. - API Standards — Style guide, naming, paths, security, error handling. Source of truth for conventions. Look for a heading like
# API Standards,# Style Guide, or similar. - OpenAPI Best Practices — Formatting rules, DRY principles, SDK compatibility, component structure. Source of truth for OpenAPI document quality. Look for a heading like
# OpenAPI Best Practices,# OAS Best Practices, or similar.
If any file is missing, ask the user to provide it before proceeding.
Working Example
See ~/.claude/skills/arc-create-api-spec/references/examples/ for a complete set of inputs (conference scheduling API):
conference-api-stories.md— stories (output from/arc-new-api-stories)conference-domain.md— domain modelAPI-standards.md— API standardsOpenAPI-best-practices.md— OpenAPI best practices
Step 1: Read All Inputs
Read all four files completely. Build a mental model of:
- Every endpoint from the stories (method + resource + parameters)
- Every data object and enum from the domain
- Every convention from the standards
- Every formatting rule from the best practices
Step 2: Generate the OpenAPI Document
Output a single valid JSON file. Default to OpenAPI 3.1.0 unless the user specifies a different version.
Structure
Follow this order in the document:
openapi— "3.1.0" (or the user-specified version)info— Title, description, version, contact, license (per best practices)servers— At least one server with descriptionsecurity— Global security scheme if standards require authtags— One tag per theme from the storiespaths— All endpoints from the storiescomponents— schemas, parameters, responses, headers, securitySchemes
Schema Generation Rules
- Every domain object becomes a component schema. Use the exact property names from the domain file.
- Every enum becomes a component schema. Don't inline enums.
- Collection responses get their own schema. e.g.,
InstrumentCollectionwithdataarray + pagination fields. - Error responses use RFC 9457 (Problem Details) unless standards specify otherwise.
- No inline schemas. Extract everything to
components/schemasand$refit. - Reusable parameters go in
components/parameters. Pagination params (cursor,limit), common filters — define once, reference everywhere. - Reusable response objects go in
components/responses. Error responses (400, 401, 404, 429, 500) — define once per unique shape. - Reusable headers go in
components/headers. Rate limit headers etc.
Content Rules
- Every operation, parameter, schema, property, response, and header MUST have a non-empty
description. - Every schema and parameter MUST have an
examplevalue. Use realistic examples from the domain file. - Every operation MUST have a
summaryandoperationId. - Error examples must match the error type (a 429 example should describe rate limiting, not "bad request").
- Use
$refaggressively. The document should be DRY.
Naming Rules
- operationIds: camelCase verbs matching the story action (e.g.,
searchInstruments,getInstrumentByFigi) - Tags: Match theme names from stories
- Schemas: PascalCase matching domain object names
- Parameters: camelCase matching domain property names
- Domain versus standards: the domain wins. When a name or value from the domain conflicts with a naming rule in the standards (for example enum values
Keynote, Talkagainst lowercase enum values, orstartTimeagainst timestamps ending inAt), keep the domain's version in the spec. Do not rename it, not even to satisfy the linter. Writing a domain label in the casing convention of the standards is not a rename: the propertyIDbecomesid,Track IDorTrackIDbecomestrackId. Words, suffixes and enum values stay as the domain has them. - Naming Decisions. Every such conflict is a naming decision: the domain name, the standards rule it departs from, and "domain applied". Take over the
## Naming Decisionssection of the stories, add any conflict you meet while writing the spec, and list them all in the report (Step 6), so the user can change the domain if the standards should win.
What NOT to Add
- Do not add endpoints that aren't in the stories
- Do not add properties that aren't in the domain
- Do not add security schemes that aren't in the standards
- If stories are simple (no error codes listed), still add standard error responses (400 for collection endpoints with filters, 404 for single-resource endpoints, 401 if auth is required, 429 rate limiting, 500 server error)
Step 3: Validate JSON
Before writing the file:
- Ensure the output is valid JSON (no trailing commas, no duplicate keys)
- Ensure every
$refpoints to a component that exists - Ensure every component is referenced at least once (no orphans)
- Ensure no
nullablekeyword is used (use"type": ["string", "null"]instead per 3.1.0)
Step 4: Save the File
Save as JSON to a location the user specifies, or ask where they'd like it saved. No specific naming convention required.
Never overwrite an existing file, and do not read existing files. Check only whether the chosen name is taken. If it is, append a number (-2, -3, ...) before the extension, save under the new name, and tell the user the final path. When you save a fixed version after linting, overwrite only the spec you wrote in this run.
Step 5: Lint with the Bundled Linter
Run the linter on the saved file. Pass the same standards and best-practices files you used as inputs, so their rules apply too. On Windows, write python instead of python3, here and in Step 6:
python3 ~/.claude/skills/arc-create-api-spec/scripts/lint_spec.py [/path/to/spec.json] \
--standards [/path/to/API-standards.md] \
--best-practices [/path/to/OpenAPI-best-practices.md] \
--json
Use --json when you read the result yourself; show the user the text report (the same call without --json) when they want to see it. Report, messages and rule codes are in English.
What it checks:
- Structure against OpenAPI 3.0 and 3.1: required fields, resolvable
$refs, path parameters, duplicate keys,nullablein 3.1. - The RateMyOpenAPI rules, rebuilt from its public source code with the same weights, so the scores read like an RMOA report.
- The Common Gotchas below: missing
descriptionandexample, orphaned components, inline schemas and enums, missing error responses, missingoperationId, missingsecuritySchemes. - Rules from the standards and best-practices files. Each such rule switches on only when its file is passed and mentions its topic (for example
application/problem+jsonortotalCount). With another organization's standards, rules whose topic the file does not mention stay off; check those parts of the standards yourself.
The result has an overall score and four category scores, 0 to 100. Every finding has a severity (error or warning), a location as a JSON pointer, the rule code and its source, and a fix hint. Broken JSON or YAML syntax is an error with the line number. Exit code 0 means no errors, 1 means at least one error, 2 means a wrong call (missing file, unknown rule code).
Interpreting Results
Scores four categories (0-100 each):
- Docs — Descriptions, summaries, examples
- Completeness — Required fields, response codes, schemas
- SDK Generation — operationIds, no inline schemas, proper refs
- Security — Auth schemes, 401/403 responses
Target: 100/100 on all categories.
Handling Issues
-
Auto-fix anything that's clearly a formatting or completeness issue (missing description, missing example, missing error response).
-
Ask the user about issues that involve design decisions. Common examples:
- No authentication / missing 401: If the API intentionally has no auth (e.g., a training exercise), tell the user the linter flagged it and ask if they want to ignore it or add auth.
- Missing error codes: If the linter expects 401/403 but the stories don't include auth, ask.
- Naming conventions: If the linter flags a naming pattern that conflicts with the standards file, the standards file wins. Tell the user.
- Domain versus standards: Where a domain name conflicts with a naming rule in the standards, the domain applies (see Naming Rules). If the linter flags such a name, for example
enum-casingon a domain enum, do not rename it and do not auto-fix it. Tell the user which finding belongs to which naming decision. Add the rule code to--ignoreonly when every finding of that rule is such a decision; otherwise leave the findings in the report and name the ones that are decisions.
-
Re-run after fixes. For every rule the user approved ignoring, add its code to
--ignore(comma-separated, for example--ignore security-global,security-schemes,response-401). Ignored findings leave the score and the exit code and are listed separately. Keep iterating until either:- Score is 100/100, or
- Remaining issues are intentional design choices the user has approved ignoring
Common Gotchas
- No-auth APIs lose points on Security. The bundled conference example scores 93 overall and 80 on Security, with
security-global,security-schemesand oneresponse-401per operation. If the API intentionally has no auth, these are expected. Confirm with the user and re-run with--ignore security-global,security-schemes,response-401. - Naming decisions in the example. The conference domain has the enum values
Keynote, Talk, Workshop, Panel; the standards want lowercase. The spec keeps the domain values, and the linter reports oneenum-casingfinding onTalkFormat. That finding is a naming decision, so addenum-casingto--ignore; together with the three no-auth codes the example then scores 100. nullablekeyword. OpenAPI 3.1.0 droppednullable. Use"type": ["string", "null"]instead. The linter reports this as an error.- Missing descriptions/examples. The most common deductions. Every operation, parameter, schema property, and response needs both. Don't skip headers either.
- Orphaned components. The linter flags schemas defined in
componentsbut never$ref'd. Remove them or wire them up. - Inline schemas. Any schema defined directly in a path (not via
$ref) hurts the SDK Generation score. Extract tocomponents/schemas. - Invalid examples. An
examplethat does not match its schema (wrong format, value outside the enum, missing required field) costs Docs and Completeness. A wrong example in a component also shows up in every collection example that repeats it. - YAML input. The linter and the preview read JSON and YAML, with their own YAML reader from the standard library. Values follow YAML 1.2:
yesand dates stay strings, but an unquotedopenapi: 3.1is a number. Write3.1.0or quote it. This skill writes JSON anyway. - Placeholder server URL. A server URL on
example.comcosts points (server-not-example). Do not invent a domain: ask the user for the real or planned host. If there is none yet, keepexample.comand listserver-not-exampleunder ignored issues.
Step 6: Report
Show the user:
## OpenAPI Spec Complete
**File:** [path]
**Score:** [Overall] / 100
- Docs: [score]
- Completeness: [score]
- SDK Generation: [score]
- Security: [score]
**Linted with:** lint_spec.py, rule files [names of the standards and best-practices files]
**Issues ignored (by design):**
- [rule code and reason for each code passed to --ignore]
**Naming decisions (domain applied):**
- [each conflict between a domain name and a standards rule, from the stories' `## Naming Decisions` and from writing the spec, with the linter finding it caused, if any; "none" if there are none]
**Deviations from the domain:**
- [every name or value that differs from the domain file beyond casing, with the reason, for example a change the user asked for; "none" if there are none]
Then ask: "Want to preview it?"
If yes, write the preview and open it with the system's default program:
python3 ~/.claude/skills/arc-create-api-spec/scripts/preview_spec.py [/path/to/spec.json] --open
The script writes [spec-name].preview.html next to the spec: one self-contained HTML file in neutral styling with system fonts and light and dark mode, readable offline. It contains no script and sends no request anywhere, also not to the API's servers. If --open cannot find a program, give the user the path to open by hand. If the user wants it in their own visual identity, they can ask for that separately.
There is no server to stop. After the user has finished reviewing, ask: "Keep the preview file or delete it?" Delete [spec-name].preview.html only on their answer.
Key Principles
-
The stories are the spec's requirements. Every story becomes one or more operations. No more, no less.
-
The domain is the schema's source of truth. Property names, types, enums, relations — all come from the domain file exactly as written.
-
The standards govern conventions. Naming, nesting, pagination, error format, auth — standards file wins over any default. Where a domain name conflicts with a naming rule, the domain wins and the conflict becomes a naming decision.
-
The best practices govern OpenAPI quality. DRY, descriptions, examples, component extraction — best practices file wins over shortcuts.
-
Lint is validation, not gospel. The linter catches real issues but also flags intentional design choices. The user decides what to fix and what to ignore.
-
JSON output only. OpenAPI in JSON, not YAML. This avoids YAML formatting issues with LLM output; the linter and the preview still read YAML specs from elsewhere.