rails-cto-api

The JSON API skill. Governs everything under the Api:: namespace.

What it does

Ensures Rails JSON APIs follow OpenAPI 3.x conventions so that documentation stays accurate, clients can be auto-generated, and the API behaves predictably for third-party integrators. Rules the skill enforces:

• All API code lives under Api::V1:: (or higher version)
• Controllers inherit from Api::V1::BaseController
• JSON responses use serializers, not render json: with inline hashes
• Authentication is handled by an API key or token, not session cookies
• Pagination uses cursor-based params, not page/per_page
• Rate limits are declared at the controller level
• Every endpoint has a matching OpenAPI spec entry
• CORS rules are explicit and documented

When it triggers

• Creating, modifying, or debugging any controller under app/controllers/api/**
• Touching serializers in app/serializers/
• Editing routes inside a namespace :api block
• When you mention api, endpoint, api key, serializer, openapi, swagger, api documentation, cors, rate limit, pagination cursor, or api versioning

Example

You: Add an endpoint that returns a user's bookmarks.

Agent: [invokes /rails-cto-api]
       [adds Api::V1::BookmarksController with an index action]
       [adds Api::V1::BookmarkSerializer]
       [updates routes.rb inside namespace :api, namespace :v1]
       [adds the endpoint to the OpenAPI spec]
       [invokes /rails-cto-qa after the .rb changes]

View source

skills/rails-cto-api/SKILL.md on GitHub →