The Complete Production SOP: How to Deploy and Run Insomnia Document-Driven REST Designer in Autonomous AI Agents

Autonomous runtimes like Claude Code and Cursor scan local directories (~/.claude/skills, .cursor/rules, or .agents/skills) to dynamically mount domain skills. Placing SKILL.md inside the workspace ensures the agent parses triggers like 'design api spec in insomnia' and applies strict OpenAPI formatting parameters without hallucinating bespoke schemas.

---
name: "insomnia-api-spec-designer"
description: "Design, test, and document REST and GraphQL APIs using Insomnia Git sync."
triggers:
  - "design api spec in insomnia"
  - "chain requests insomnia"
  - "sync insomnia with git"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

Insomnia models environments as hierarchical JSON objects containing base variables and sub-environment overrides (e.g., base_url, api_version). To avoid token leakage in Git repositories synced with Insomnia, instruct the agent to declare variable placeholders using the {{ _.variable_name }} syntax and maintain secret mapping exclusively in environment files excluded by .gitignore.

{
  "_type": "environment",
  "parentId": "wrk_default",
  "name": "Base Environment",
  "data": {
    "base_url": "http://localhost:8080/v1",
    "api_version": "v1"
  }
}

When prompted with triggers like 'chain requests insomnia', the agent creates an authentication endpoint alongside dependent endpoints. Downstream requests reference the authentication response token dynamically via Nunjucks expressions, eliminating manual copy-pasting of JSON Web Tokens.

{
  "_type": "request",
  "url": "{{ _.base_url }}/users/me",
  "method": "GET",
  "headers": [
    {
      "name": "Authorization",
      "value": "Bearer {% response 'body', 'req_login_001', 'b64::JC5hY2Nlc3NfdG9rZW4=::46e', 'never', 60 %}"
    }
  ]
}

Before committing changes to the Git branch linked to Kong Insomnia, the agent must run validation to confirm OpenAPI syntax compliance and assert that all request/response models contain description fields and schema types.

openapi: 3.1.0
info:
  title: Payment Gateway Service
  version: 1.0.0
  description: Production-grade billing and checkout API
paths:
  /checkout:
    post:
      summary: Process transaction
      operationId: processCheckout
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionId:
                    type: string