Skip to main content
Generalmelodic-software

ears-convert

Convert specifications to/from EARS format.

Stars
74
Source
melodic-software/claude-code-plugins
Updated
2026-04-07
Slug
melodic-software--claude-code-plugins--ears-convert
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/melodic-software/claude-code-plugins/HEAD/plugins/spec-driven-development/skills/ears-convert/SKILL.md -o .claude/skills/ears-convert.md

Drops the SKILL.md into .claude/skills/ears-convert.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

EARS Format Conversion

Convert specifications between EARS format and other formats.

Supported Conversions

From To Description
Prose EARS Natural language to structured EARS
EARS Prose EARS to readable natural language
EARS Gherkin EARS to Given/When/Then scenarios
Gherkin EARS Gherkin scenarios to EARS requirements
EARS Canonical EARS list to canonical specification
Canonical EARS Extract EARS requirements from spec

Workflow

  1. Load Source

    • Read source file
    • Detect current format

  2. Analyze Content

    • Parse requirements or scenarios
    • Identify patterns and structure

  3. Convert

    • Spawn spec-converter ears agent
    • Transform to target format
    • Preserve semantic meaning

  4. Validate

    • Check target format compliance
    • Verify content preservation

  5. Output

    • Write to file or display

Arguments

  • $1 - Source file path
  • --to - Target format: ears, canonical, prose, gherkin
  • --output - Output file path (optional)

Examples

# Prose to EARS
/spec-driven-development:ears-convert requirements.txt --to ears

# EARS to Gherkin
/spec-driven-development:ears-convert ears-requirements.md --to gherkin

# EARS to readable prose
/spec-driven-development:ears-convert spec.md --to prose

# Specify output
/spec-driven-development:ears-convert input.md --to ears --output output.md

Conversion Examples

Prose → EARS

Input (Prose):

Users should be able to log in using their email and password.
The system needs to validate credentials before granting access.

Output (EARS):

## FR-1: User Authentication

WHEN the user submits login credentials,
the system SHALL validate the email and password
AND grant access if credentials are valid.

EARS → Gherkin

Input (EARS):

WHEN the user submits valid credentials,
the system SHALL create a session token.

Output (Gherkin):

Scenario: Successful login creates session
  Given a user with valid credentials
  When the user submits the login form
  Then a session token is created
  And the user is redirected to dashboard

EARS → Prose

Input (EARS):

WHILE the user is authenticated,
the system SHALL display the user's name in the header.

Output (Prose):

When a user is logged in, the system shows their name in the page header.
This ensures users can confirm they're using the correct account.

Pattern Preservation

The converter preserves EARS pattern semantics:

EARS Pattern Preserved As
WHEN...SHALL Gherkin When...Then
WHILE...SHALL Gherkin Given (state)...Then
IF...THEN...SHALL Gherkin error scenario
WHERE...SHALL Gherkin @tag scenario

Related Commands

  • /spec-driven-development:ears-author - Create EARS requirements
  • /spec-driven-development:gherkin-convert - Gherkin conversions
  • /spec-driven-development:convert - General format conversion