agentsclimarketplace

Backend api contract

Skill parhumm/jaan-to/skills/backend-api-contract

Generate OpenAPI 3.1 contracts with schemas, RFC 9457 errors, versioning, and examples. Use when defining API contracts from entities.From its SKILL.md

Install
npx -y skills add parhumm/jaan-to --skill backend-api-contract

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.

What its file declares

Copied from the file, not written here

The file declares its own license as PROPRIETARY. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

15.5 KB, as published. Nobody here has run it

backend-api-contract

Generate production-quality OpenAPI 3.1 contracts from API resource entities.

Context Files

  • $JAAN_CONTEXT_DIR/tech.md - Tech stack context (optional, auto-imported if exists)
    • Uses sections: #current-stack, #frameworks, #constraints, #versioning, #patterns
  • $JAAN_CONTEXT_DIR/config.md - Project configuration
  • $JAAN_TEMPLATES_DIR/jaan-to-backend-api-contract.template.md - Output template
  • $JAAN_LEARN_DIR/jaan-to-backend-api-contract.learn.md - Past lessons (loaded in Pre-Execution)
  • ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocol

Input

API Entities: $ARGUMENTS

Accepts any of:

  • Entity list — Comma-separated resource names (e.g., "User, Post, Comment")
  • PRD reference — Path to PRD file with API requirements
  • Database schema — Path to DDL/migration file
  • Existing spec — Path to existing OpenAPI file for enhancement

If no input provided, ask: "What API resources should be included?"


Pre-Execution Protocol

MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md Skill name: backend-api-contract Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding)

Also read tech context if available:

  • $JAAN_CONTEXT_DIR/tech.md - Know the tech stack for framework-specific patterns (versioning, auth, error format)

Language Settings

Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md Override field for this skill: language_backend-api-contract

Language exception: Generated code output (variable names, code blocks, schemas, SQL, API specs) is NOT affected by this setting and remains in the project's programming language.


PHASE 1: Analysis (Read-Only)

Thinking Mode

ultrathink

Use extended reasoning for:

  • Analyzing input to extract API resource structure
  • Mapping resource relationships and CRUD operations
  • Designing schema composition strategy (flat components, $ref hierarchy)
  • Planning endpoint structure, error handling, and pagination

Step 1: Parse Input

Analyze the provided input to extract API resources:

If entity list:

  1. Split comma-separated names
  2. Infer resource types (collection, singleton, nested)
  3. Note any implied relationships (e.g., "Comment" implies parent "Post")

If PRD reference:

  1. Read the PRD file
  2. Extract API-relevant user stories and acceptance criteria
  3. Identify resources, operations, and data requirements
  4. Note technical constraints mentioned

If database schema:

  1. Read DDL/migration file
  2. Extract tables, columns, types, constraints
  3. Map foreign keys to resource relationships
  4. Identify indexes that imply query patterns

If existing spec:

  1. Read the OpenAPI file
  2. Identify gaps (missing schemas, error responses, examples)
  3. Offer enhancement vs. regeneration

Build initial understanding:

INPUT SUMMARY
─────────────
Type:        {input-type}
Resources:   {resources}
Relationships: {implied relationships}
Unknown:     {unclear areas}

Step 2: Clarify API Design

Ask up to 6 smart questions based on what's unclear from Step 1. Skip questions already answered by the input or tech.md.

Scope question (ask if multiple resources):

  1. Use AskUserQuestion:
    • Question: "Which resources should be included in this contract?"
    • Header: "Scope"
    • Options:
      • "All listed" — Generate contract for all identified resources
      • "Select specific" — Let me choose which resources to include
      • "Priority subset" — Start with core resources, add others later

Design questions (ask if not in tech.md): 2. Use AskUserQuestion:

  • Question: "Which API versioning strategy should be used?"
  • Header: "Versioning"
  • Options:
    • "URL path /v1/ (Recommended)" — Most visible, cache-friendly, separate spec per version
    • "Header (API-Version)" — Clean URLs, less discoverable
    • "No versioning" — API evolution with additive-only changes
    • "Date-based (Stripe style)" — e.g., v2024-01-15 for major breaks
  1. Use AskUserQuestion:

    • Question: "What authentication method does this API use?"
    • Header: "Auth"
    • Options:
      • "OAuth2 + JWT (Recommended)" — Full OAuth2 flow with JWT tokens
      • "API Key" — Simple key in header or query param
      • "JWT Bearer only" — Direct JWT without OAuth2 flow
      • "None" — No authentication required
  2. Use AskUserQuestion:

    • Question: "What level of detail should the contract include?"
    • Header: "Depth"
    • Options:
      • "Production (Recommended)" — Full schemas, validation rules, examples, all error codes
      • "MVP" — Core CRUD operations, basic schemas, minimal examples
      • "Framework only" — Schemas and components only, no paths
  3. Use AskUserQuestion:

    • Question: "Which pagination strategy for list endpoints?"
    • Header: "Pagination"
    • Options:
      • "Cursor-based (Recommended)" — Consistent results, scalable, opaque cursor + has_more
      • "Offset-based" — Simple page + limit, less scalable
      • "None" — No pagination needed

Ownership question (always ask): 6. Use AskUserQuestion:

  • Question: "Who are the primary API consumers?"
  • Header: "Consumers"
  • Options:
    • "Internal frontends" — Web/mobile apps owned by same team
    • "Third-party developers" — External integrators, needs comprehensive docs
    • "Both" — Internal and external consumers
    • "Machine-to-machine" — Service-to-service, no human consumers

Step 3: Resource Relationship Mapping

For each resource, determine:

AttributeOptionsExample
TypeCollection / Singleton / Nested / ActionCollection
Relationships1:N / M:N / Polymorphic / NoneUser 1:N Posts
CRUDWhich HTTP methods neededGET, POST, PATCH, DELETE
FieldsName, type, constraintsemail: string, format: email
NullableWhich fields can be nullbio: ["string", "null"]

Present resource map:

RESOURCE MAP
────────────
Resource: User
  Type:       Collection
  Fields:     id (uuid), email (email), name (string), role (enum), bio (nullable string), created_at, updated_at
  Relations:  1:N → Posts, 1:N → Comments
  Operations: List, Create, Read, Update, Delete
  Custom:     Verify email (POST /users/{id}/verify)

Resource: Post
  Type:       Collection (nested under User optional)
  Fields:     id (uuid), title (string), body (string), status (enum: draft/published), author_id (uuid)
  Relations:  N:1 → User, 1:N → Comments
  Operations: List, Create, Read, Update, Delete, Publish (action)

Step 4: Schema Design Strategy

Plan the component architecture using research-informed patterns.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-api-contract-reference.md — "Schema Design Patterns" for base schemas, per-resource schemas, shared components, and design rules.

Present schema plan:

SCHEMA PLAN
───────────
Base schemas:     {count} (Timestamps, ProblemDetails, ValidationProblemDetails, PaginationMeta)
Resource schemas: {count} ({Resource}, {Resource}Create, {Resource}Update, {Resource}Response, {Resource}List × N)
Shared params:    {count}
Shared responses: {count}
Named examples:   {count}
Total components: {total}

HARD STOP — Review Contract Plan

API CONTRACT PLAN
═════════════════

RESOURCES ({count})
───────────────────
{resource1} ({op_count} ops)
{resource2} ({op_count} ops)
...

SCHEMAS ({count} total)
───────────────────────
Base:     {count} (Timestamps, ProblemDetails, ValidationProblemDetails, PaginationMeta)
Resource: {count} (5 per resource × {resource_count})
Shared:   {count} (params, responses, examples)

ENDPOINTS ({count} total)
─────────────────────────
Auth:       {strategy}
Versioning: {strategy}
Errors:     RFC 9457 Problem Details
Pagination: {strategy}
Consumers:  {audience}

STATUS CODES
────────────
Success: 200 (GET/PATCH), 201 (POST), 204 (DELETE)
Client:  400, 401, 403, 404, 409, 422, 429
Server:  500

OUTPUT
──────
Main:      api.yaml (OpenAPI 3.1)
Companion: {id}-{slug}.md (quick-start guide)

Use AskUserQuestion:

  • Question: "Proceed with generating the OpenAPI 3.1 contract?"
  • Header: "Generate"
  • Options:
    • "Yes" — Generate the contract
    • "No" — Cancel
    • "Edit" — Let me revise the scope or design first

Do NOT proceed to Phase 2 without explicit approval.


PHASE 2: Generation (Write Phase)

Step 5: Generate OpenAPI YAML

Read template: $JAAN_TEMPLATES_DIR/jaan-to-backend-api-contract.template.md

If tech stack needed, extract sections from tech.md:

  • Current Stack: #current-stack
  • Frameworks: #frameworks
  • Constraints: #constraints
  • Versioning: #versioning
  • Patterns: #patterns

Generate the OpenAPI 3.1 YAML in this order (minimizes broken $ref):

  1. Header: openapi: 3.1.0, info (title, version, description, contact, license), servers
  2. Tags: One per resource, with description
  3. Components (define before referencing): a. securitySchemes — Based on auth choice from Step 2 b. schemas — Base schemas first (Timestamps, ProblemDetails, ValidationProblemDetails, PaginationMeta), then resource schemas in dependency order c. parameters — CursorParam, LimitParam, path ID params d. responses — Shared error responses referencing ProblemDetails schemas e. examples — Named examples per operation (happy path, edge cases)
  4. Paths: All operations grouped by resource, referencing components via $ref
  5. Security: Global security requirement

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-api-contract-reference.md — "Generation Rules" for schema rules, operation rules, status codes per operation type, example rules, and pagination format.

Step 6: Generate Companion Markdown

Generate a companion markdown guide covering: Executive Summary, Authentication, Quick Start (cURL examples), Pagination, Error Handling (RFC 9457), Resources endpoint table, Validation & Tooling commands, and Metadata.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-api-contract-reference.md — "Companion Markdown Structure" for the full template with examples.

Step 7: Quality Check

Before preview, verify all structural (OpenAPI 3.1), error handling, and completeness checks pass. If any check fails, fix before preview.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/backend-api-contract-reference.md — "Quality Checklist" for the full verification checklist.

Step 8: Preview & Approval

Use AskUserQuestion:

  • Question: "Write the contract files to output?"
  • Header: "Write"
  • Options:
    • "Yes" — Write both files
    • "No" — Cancel
    • "Edit" — Let me revise something first

Step 8.5: Generate ID and Folder Structure

If approved, set up the output structure:

  1. Source ID generator utility:
source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/id-generator.sh"
  1. Generate sequential ID and output paths:
# Define subdomain directory
SUBDOMAIN_DIR="$JAAN_OUTPUTS_DIR/backend/api-contract"
mkdir -p "$SUBDOMAIN_DIR"

# Generate next ID
NEXT_ID=$(generate_next_id "$SUBDOMAIN_DIR")

# Create folder and file paths (slug from API name)
slug="{lowercase-hyphenated-api-name}"
OUTPUT_FOLDER="${SUBDOMAIN_DIR}/${NEXT_ID}-${slug}"
MAIN_FILE="${OUTPUT_FOLDER}/api.yaml"
COMPANION_FILE="${OUTPUT_FOLDER}/${NEXT_ID}-${slug}.md"
  1. Preview output configuration:

Output Configuration

  • ID: {NEXT_ID}
  • Folder: $JAAN_OUTPUTS_DIR/backend/api-contract/{NEXT_ID}-{slug}/
  • Main: api.yaml
  • Companion: {NEXT_ID}-{slug}.md

Step 9: Write Output

  1. Create output folder:
mkdir -p "$OUTPUT_FOLDER"
  1. Write OpenAPI spec to api.yaml

  2. Write companion guide to {NEXT_ID}-{slug}.md

  3. Update subdomain index:

source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/index-updater.sh"
add_to_index \
  "$SUBDOMAIN_DIR/README.md" \
  "$NEXT_ID" \
  "${NEXT_ID}-${slug}" \
  "{API Title}" \
  "{executive-summary}"
  1. Confirm completion:

✓ Contract written to: $JAAN_OUTPUTS_DIR/backend/api-contract/{NEXT_ID}-{slug}/api.yaml ✓ Guide written to: $JAAN_OUTPUTS_DIR/backend/api-contract/{NEXT_ID}-{slug}/{NEXT_ID}-{slug}.md ✓ Index updated: $JAAN_OUTPUTS_DIR/backend/api-contract/README.md

Step 9a: Generate Spectral Config Companion

Generate a .spectral.yaml companion file alongside the contract:

extends:
  - "spectral:oas"
  - "spectral:asyncapi"
rules:
  operation-operationId: error
  operation-description: warn
  oas3-api-servers: error
  no-$ref-siblings: error

If OWASP ruleset is relevant (auth endpoints detected), add:

extends:
  - "spectral:oas"
  - "@stoplight/spectral-owasp-ruleset"

Write to: $OUTPUT_FOLDER/.spectral.yaml

Add "Validation Commands" section to companion markdown guide:

## Validation Commands

Lint this contract:
  npx @stoplight/spectral-cli lint api.yaml --ruleset .spectral.yaml

Mock server:
  npx @stoplight/prism-cli mock api.yaml

Contract validation (full pipeline):
  /jaan-to:qa-contract-validate api.yaml

Step 10: Suggest Next Steps

"Contract generated. Suggested next steps:"

  1. Lint contract: npx @stoplight/spectral-cli lint api.yaml --ruleset .spectral.yaml
  2. Mock server: npx @stoplight/prism-cli mock api.yaml
  3. Full validation: /jaan-to:qa-contract-validate {output-path}/api.yaml
  4. Generate client SDK: npx orval --input api.yaml --output ./src/api/
  5. Contract tests: schemathesis run api.yaml
  6. API documentation: /jaan-to:dev-docs-generate

Step 11: Capture Feedback

Use AskUserQuestion:

  • Question: "Any feedback on the generated contract?"

  • Header: "Feedback"

  • Options:

    • "No" — All good, done
    • "Fix now" — Update something in the contract
    • "Learn" — Save lesson for future runs
    • "Both" — Fix now AND save lesson
  • Fix now: Update the output files, re-preview, re-write

  • Learn: Run /jaan-to:learn-add backend-api-contract "{feedback}"

  • Both: Do both


Skill Alignment

  • Two-phase workflow with HARD STOP for human approval
  • Multi-stack support via tech.md detection
  • Template-driven output structure
  • Output to standardized $JAAN_OUTPUTS_DIR path

Definition of Done

  • Input parsed, resources identified and confirmed
  • API design decisions confirmed (versioning, auth, errors, pagination, consumers)
  • Resource relationships mapped with fields and operations
  • Schema hierarchy designed (flat components, $ref strategy)
  • OpenAPI 3.1 YAML generated with all components and paths
  • Companion markdown guide generated with Executive Summary
  • Quality checks passed (structural, error handling, completeness)
  • Output written to $JAAN_OUTPUTS_DIR/backend/api-contract/{id}-{slug}/
  • Subdomain index updated
  • User approved final result

Keep looking

Skills are one crate of 613,531. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.