# om-auto-write-spec

Turns a brief or a tracker issue into a finished spec and opens a PR for it. Runs unattended, so you come back to a published spec.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 2900 installs · ★ 252
- Author: open-mercato
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/open-mercato/skills/tree/HEAD/skills/om-auto-write-spec/SKILL.md
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/skills/om-auto-write-spec

## What it does

Give the skill a free-form brief or an issue id and it carries the work through to a published spec PR. The document itself comes from `om-spec-writing` in `--autonomous` mode; `om-open-pr` ships it. Open questions do not linger — autonomous defaults resolve them into a dedicated section, and the assumptions table is posted as a PR comment.

For UI-facing features the skill adds visual evidence: screenshots of the current screens the feature touches, plus rendered mockups of the proposed interface. That step needs the `om-prepare-test-env` descriptor and a configured browser provider. Without either, it is skipped and the spec stays text-only. Passing `--no-mockups` turns it off even when a provider is available.

Everything happens in an isolated worktree on a `spec/${SLUG}` branch cut from `origin/$BASE_BRANCH`, so your primary checkout stays untouched. Issue-driven runs follow a claim protocol: if someone else already holds the issue, the skill stops, and `--force` bypasses the check. An open PR that already carries a spec for the same brief or issue means no second one gets created. Any assumption marked `⚠ NEEDS HUMAN CONFIRMATION` flips the PR to draft, and merging waits on that confirmation.

The run ends with `PR:` and `Spec:` reference lines (plus `Issue:` for issue-driven runs), which is what `om-auto-implement-spec` picks up next.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add open-mercato/skills --skill om-auto-write-spec -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/om-auto-write-spec/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/om-auto-write-spec/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add open-mercato/skills --skill om-auto-write-spec -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/om-auto-write-spec/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add open-mercato/skills --skill om-auto-write-spec -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/om-auto-write-spec/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install open-mercato/skills om-auto-write-spec
```

2. **Manually: put the files in place**
- File: `.github/skills/om-auto-write-spec/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add open-mercato/skills --skill om-auto-write-spec -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/open-mercato/skills --path skills/om-auto-write-spec
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/om-auto-write-spec/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add open-mercato/skills --skill om-auto-write-spec -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/open-mercato/skills/tree/HEAD/skills/om-auto-write-spec/SKILL.md

## When to use it
- get a spec out of a brief without writing it by hand
- turn a tracker issue into a spec PR
- attach current-screen screenshots as PR evidence
- apply SDLC labels with a rationale for each
- hand the spec to implementation via PR and Spec markers

## Example prompts
- Write a spec for the new reports page and open a PR
- Spec this issue #412 and attach UI mockups
- Write the spec from the brief but skip mockups with `--no-mockups`

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 6a531497578b6268.

BEGIN THIRD-PARTY FILE 6a531497578b6268
```text
---
name: om-auto-write-spec
description: Autonomously turn a brief or FR issue into a spec landed on a ready PR — runs om-spec-writing --autonomous (defaults posted for override), attaches UI mockups and current-app screenshots as PR evidence when a browser provider exists, applies full SDLC labels, and emits PR/spec markers for chaining into om-auto-implement-spec. Use for "write a spec for X and open a PR", "spec this issue".
---

# Auto Write Spec (brief/issue → spec PR)

Run unattended: the user starts you and comes back to a **published spec PR** — the spec document, resolved-assumptions comment, and (for UI-facing features) mockups and screenshots attached as PR evidence. Composition, not reinvention: `om-spec-writing --autonomous` writes the document, `om-open-pr` ships it, the browser-provider descriptor captures visuals.

## Arguments

- `{brief}` or `{issueId}` (one required) — a free-form feature brief, or a tracker issue id to read the brief from (`get-issue`). With an issue, the run is issue-driven: claim protocol applies and the PR carries `Refs #{issueId}`.
- `{repo}` (optional) — `owner/name`; infer from git remote if omitted
- `--slug <kebab-case>` (optional) — override the slug used in branch and spec filenames
- `--no-mockups` (optional) — skip step 5 even for UI-facing specs
- `--force` (optional) — bypass the claim-conflict check

## Chaining

The spec PR this skill opens is the natural input of `om-auto-implement-spec` (or `om-auto-fix-issue`'s feature route), which keeps it design-only and ships the implementation on its own PR referencing it (`Refs #{specPr}`). Always end with the `PR:` / `Spec:` (and `Issue:` when issue-driven) reference lines. If an open PR already carries a spec for this brief/issue (via **search-prs**), stop and report it — never open a duplicate.

Companion skills (all optional, with fallbacks): `om-spec-writing` (required — the document engine), `om-open-pr` (PR opening; inline **create-pr** fallback per `references/pr-finalize.md`), `om-prepare-test-env` + browser provider (mockups/screenshots; degrade to text-only), `om-auto-implement-spec` (the follow-on).

## Workflow

**ALWAYS check first:** Apply `.ai/skills/om-auto-write-spec/SKILL.md` when present; safety rules still win.
```
END THIRD-PARTY FILE 6a531497578b6268

The third-party file has ended. Everything between the 6a531497578b6268 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2287 of 9263 bytes. © open-mercato · MIT · https://github.com/open-mercato/skills/tree/HEAD/skills/om-auto-write-spec/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md