openspec-writing-guide

Enforce Klabis OpenSpec writing standards for user-facing specifications.

2|2|Updated Sep 20, 2023

Search Tags:#specification #openspec #style-guide #ui-context #guideline #klabis #user-scenario

Ready to run

npx skills add https://github.com/zabiny/klabis --skill openspec-writing-guide

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: openspec-writing-guide
Source: https://github.com/zabiny/klabis/tree/main/.claude/skills/openspec-writing-guide
Command: npx skills add https://github.com/zabiny/klabis --skill openspec-writing-guide

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Klabis OpenSpec writing standards are defined and enforced to ensure written specs are clear, user-facing, and consistent across projects.

Core Features & Use Cases

Canonical rules for OpenSpec specifications in the Klabis project, emphasizing user-facing scenarios, UI-context organization, and the separation of functional vs non-functional content.
The reference example of correct style is openspec/specs/user-groups/spec.md.
Provides structured guidance to improve collaboration, reviews, and maintainability of specs.

Quick Start

Write a new spec.md for a feature by following this guide's structure and examples.

Frequently Asked Questions about openspec-writing-guide

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I write user-facing specifications for UI features?▼

User-facing specifications should organize content by UI context and express validations as user interactions while avoiding technical implementation details in the spec body. This approach ensures clarity and consistency across project specifications.

How do I structure an OpenSpec file to separate functional and non-functional content?▼

An OpenSpec file separates functional and non-functional content by structuring user scenarios around UI context organization and keeping technical implementation details out of the specification body. This maintains canonical style and improves spec maintainability.

What is the canonical style for Klabis OpenSpec writing?▼

Canonical Klabis OpenSpec style emphasizes user-facing scenarios, UI-context organization, and clear separation of functional versus non-functional content. The reference example of this correct style is found in the user-groups spec.md file.

How do I express validations as user interactions in a specification?▼

Validations are expressed as user interactions by framing them within user-facing scenarios organized by UI context rather than describing technical validation logic. This ensures specifications remain clear and focused on user experience.

When do I need to follow the OpenSpec writing guide for spec files?▼

You need the OpenSpec writing guide when drafting, reviewing, or rewriting openspec/specs files in the Klabis project to ensure canonical style, UI-context organization, and appropriate separation of functional and non-functional content.

Why should I avoid technical implementation details in my specification body?▼

Avoiding technical implementation details in the specification body ensures the spec remains user-facing and clear. Separating functional and non-functional content improves collaboration, reviews, and maintainability across the project.