omg

Use when writing or editing .omg.md files - the human-first DSL for API specification that compiles to OpenAPI 3.1

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill enables the efficient creation and editing of API specifications using OMG (OpenAPI Markdown Grammar), a human-centric DSL. It streamlines the development workflow by allowing users to write concise .omg.md files that compile into full OpenAPI 3.1 specifications, significantly reducing boilerplate and improving the maintainability of API documentation.

Use Cases

  • Rapid API Prototyping: Quickly define RESTful endpoints, request parameters, and response schemas using a simplified Markdown syntax instead of verbose YAML or JSON.
  • OpenAPI 3.1 Generation: Automatically convert human-readable DSL files into industry-standard OpenAPI 3.1 specifications for integration with documentation tools and SDK generators.
  • Schema Refactoring: Reduce the complexity of large API definitions by utilizing OMG's modular 'partials' and concise syntax, achieving up to a 6x reduction in lines of code.
  • Technical Documentation: Maintain API specifications in a format that is easy for both developers and non-technical stakeholders to read and review within a version control system.
nameomg
# IMPORTANTKeep description on ONE line for Claude Code compatibility
descriptionUse when writing or editing .omg.md files - the human-first DSL for API specification that compiles to OpenAPI 3.1

OMG (OpenAPI Markdown Grammar)

Quick Start

---
method: GET
path: /accounts/{accountId}
operationId: get-account
tags: [Accounts]
---
# Get Account
Returns details of a specific account.
```omg.path
{ accountId: uuid }
{ id: uuid, name: string, balance: decimal }

## Core Concepts

- **`.omg.md` files** - Markdown with YAML frontmatter, one endpoint per file
- **Code blocks**: `omg.path`, `omg.query`, `omg.body`, `omg.response`, `omg.response.{code}`, `omg.returns`, `omg.type`
- **Types**: `string`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `uuid`, `any`
- **Syntax**: `field?: type` (optional), `type[]` (array), `"a"|"b"` (enum), `@min(0)` (constraints)
- **Partials**: `@path/to/partial` or `{{> path/to/partial }}` for reuse

## CLI

```bash
node packages/omg-cli/dist/cli.js build api.omg.md -o output.yaml
node packages/omg-cli/dist/cli.js parse endpoint.omg.md

Notes

  • Compiles to OpenAPI 3.1, ~6x reduction in lines
  • Run npm run build before using CLI