# openspec-proposal-creation

Builds a structured change proposal: proposal.md, tasks.md and spec-delta.md with requirements in EARS format. Useful when a feature needs writing down before anyone codes it.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1200 installs · ★ 10
- Author: forztf
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/forztf/open-skilled-sdd/tree/HEAD/skills/openspec-proposal-creation/SKILL.md
- Updated: 2025-11-28
- HTML: https://affpapa.org/en/nevibecode/skills/openspec-proposal-creation

## What it does

The skill walks the agent through eight steps. First it looks at what specs already exist under `spec/specs` and which changes are open in `spec/changes`, then picks an identifier like `add-user-authentication` and checks it is free. After that it scaffolds `spec/changes/{change-id}/specs/{capability-name}` and fills it with three files.

\`proposal.md` covers why the change is happening, what shifts and who gets affected. `tasks.md` is a numbered implementation checklist, typically 5 to 15 items, including testing and documentation work. The critical piece is `spec-delta.md`: requirements follow EARS syntax under `## ADDED Requirements`, `## MODIFIED Requirements` and `## REMOVED Requirements`, and each requirement gets a scenario written as `#### Scenario:`.

Before handing the proposal over, the skill runs validation: it counts delta operations with `grep` and checks requirement and scenario headers. Skip that step and the structure drifts, which means redoing the proposal. Runs in Claude, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add forztf/open-skilled-sdd --skill openspec-proposal-creation -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add forztf/open-skilled-sdd --skill openspec-proposal-creation -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/openspec-proposal-creation/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add forztf/open-skilled-sdd --skill openspec-proposal-creation -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/openspec-proposal-creation/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install forztf/open-skilled-sdd openspec-proposal-creation
```

2. **Manually: put the files in place**
- File: `.github/skills/openspec-proposal-creation/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add forztf/open-skilled-sdd --skill openspec-proposal-creation -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/forztf/open-skilled-sdd --path skills/openspec-proposal-creation
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/openspec-proposal-creation/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add forztf/open-skilled-sdd --skill openspec-proposal-creation -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/forztf/open-skilled-sdd/tree/HEAD/skills/openspec-proposal-creation/SKILL.md

## When to use it
- spec a new feature before writing code
- capture a breaking change and its impact
- build an implementation checklist with tests
- document removal of a deprecated capability
- validate proposal structure before approval

## Example prompts
- create an openspec proposal for adding user authentication
- review existing specs and suggest a change ID for the new feature
- write a spec delta in EARS format for the API rate limit change

## Similar
- [proposal-writer](https://affpapa.org/en/nevibecode/skills/jezweb-proposal-writer.md) — skill · 1200 installs
- [investment-proposal](https://affpapa.org/en/nevibecode/skills/investment-proposal.md) — skill · 1100 installs
- [contract-and-proposal-writer](https://affpapa.org/en/nevibecode/skills/contract-and-proposal-writer.md) — skill · 747 installs
- [openspec-update-change](https://affpapa.org/en/nevibecode/skills/openspec-update-change.md) — skill · 4500 installs
- [openspec-onboard](https://affpapa.org/en/nevibecode/skills/openspec-onboard.md) — skill · 4000 installs
- [user-guide-creation](https://affpapa.org/en/nevibecode/skills/user-guide-creation.md) — skill · 751 installs

From the same set: [forztf/open-skilled-sdd](https://affpapa.org/en/nevibecode/by/forztf/open-skilled-sdd.md) — 2 cards

---
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