openspec-skills — Prompts (Verbatim)
1. openspec-proposal/SKILL.md — Full Header and Execution Steps
This skill demonstrates the "instruction-as-checklist" prompting technique used throughout the pack:
---
name: openspec-proposal
description: Create a new change proposal following the OpenSpec SDD workflow. Use when starting
a new feature, enhancement, or significant change that needs specification tracking.
allowed-tools: Read, Write, Glob, Grep, Bash
---
# OpenSpec: Proposal
Create a new change proposal following the OpenSpec Spec-Driven Development workflow.
## Execution Steps
### Step 1: Generate Change ID
Convert the description to kebab-case for the change ID.
**Example:** "add user search" → `add-user-search`
### Step 2: Create Directory Structure
mkdir -p openspec/changes/{change-id}/specs
### Step 3: Generate proposal.md
Create `openspec/changes/{change-id}/proposal.md`:
# Proposal: {Feature Title}
**Change ID:** `{change-id}`
**Created:** {YYYY-MM-DD}
**Status:** Draft
## Problem Statement
{Analyze the request and describe:}
- What problem are we solving?
- Who is affected?
- What's the current pain point?
...
## Impact Analysis
| Component | Change Required | Details |
|-----------|-----------------|---------|
| Database | Yes/No | {details} |
| API | Yes/No | {details} |
| State | Yes/No | {details} |
| UI | Yes/No | {details} |
## Risks & Mitigations
| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| {risk} | Low/Med/High | Low/Med/High | {strategy} |
Prompting technique: Imperative numbered checklist with embedded document templates. The agent is given exact file paths, exact content structures, and a summary format to output after completion. No "Iron Law" XML tags — purely instruction-as-procedure.
2. openspec-apply/SKILL.md — Context Loading Protocol
The Apply skill demonstrates "read-before-act" protocol enforcement:
---
name: openspec-apply
description: Implement a change proposal following the OpenSpec SDD workflow.
Use after a proposal is approved and ready for implementation.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---
## Execution Steps
### Step 1: Load Context
Read these files in order:
1. `openspec/project.md` - Project conventions
2. `openspec/changes/{change-id}/proposal.md` - What and why
3. `openspec/changes/{change-id}/tasks.md` - Implementation checklist
4. `openspec/changes/{change-id}/specs/*.md` - Delta specifications
### Step 3: Execute Tasks Phase by Phase
For each phase in tasks.md:
#### 3.2 Implement Task
- Follow existing patterns from project's CLAUDE.md
- Write code according to delta spec requirements
- Include tests for new functionality
#### 3.4 Quality Gate
After completing each phase, run project quality checks:
# Example for Flutter projects:
# make format && make analyze && make run_unit_test
# Example for Node projects:
# npm run lint && npm test
### Step 5: Handle Issues
If you encounter blockers:
1. Document in tasks.md under the task
2. Add a `### Blockers` section if needed
3. Ask for clarification before proceeding
- [ ] 1.2 Add search to repository
- **Blocker:** Unclear if fuzzy search should use DB or in-memory
- **Options:** A) Database query, B) In-memory filtering
- **Waiting for:** Decision from user
Prompting technique: Ordered-read protocol (forces context loading before any action), with explicit blocker-handling templates that keep the agent from silently skipping unclear requirements.
### Merge Strategy
#### For ADDED content
- Append to existing spec under appropriate section
- Maintain consistent formatting
- Add creation date comment if helpful
#### For MODIFIED content
- Replace the existing requirement
- Keep the same location in the document
- Note the modification date
#### For REMOVED content
- Move to Deprecated section (don't delete immediately)
- Include removal reason and date
- Can be fully removed in future cleanup
### Step 6: Commit the Archive
git add openspec/
git commit -m "docs(openspec): archive {change-id}
- Merged delta specs into main specs
- Archived change history
- Implementation complete"
Prompting technique: "Merge strategy" section pre-answers three common ambiguities (add/modify/remove) so the agent does not have to infer. The exact git commit message format (including the conventional commit type docs(openspec):) is specified inline to enforce consistent history.
Key Prompting Techniques Used
- Instruction-as-checklist: Each skill is a numbered step list; the agent creates a TodoWrite per step and marks them done sequentially.
- Embedded document templates: All generated file content is specified verbatim inside the skill, including placeholder labels like
{Feature Title}.
- Read-before-act ordering: The Apply skill explicitly orders the context files to read before any code is written.
- Explicit halt conditions: The Archive skill specifies exact error messages to show when preconditions fail ("Cannot archive: {X} tasks still pending").
- Convention-citing: Every skill instructs "Follow project's CLAUDE.md" as the first override layer, placing project conventions above skill defaults.