skills.rest
deicer
deicerCOMMUNITY
Explore all skills by this author →
GitHub

openspec-context-docs

Organize OpenSpec context documents under the openspec/ directory structure.

Updated Mar 8, 2026
Search Tags:#documentation#context#specification#requirements#technical writing#openspec
One-click install
npx skills add https://github.com/deicer/codex-lb --skill openspec-context-docs
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: openspec-context-docs
Source: https://github.com/deicer/codex-lb/tree/main/.agents/skills/openspec-context-docs
Command: npx skills add https://github.com/deicer/codex-lb --skill openspec-context-docs

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill addresses the challenge of maintaining clear and comprehensive documentation for OpenSpec, ensuring that normative requirements in spec.md are complemented by essential narrative context without compromising the single source of truth.

Core Features & Use Cases

  • Two-Layer Documentation: Enforces a clear separation between normative requirements (spec.md) and explanatory context (e.g., context.md, rationale.md).
  • Contextual Enrichment: Guides the inclusion of purpose, rationale, constraints, failure modes, examples, and operational notes within context documents.
  • Organized Structure: Defines specific locations for main specs, optional context splits, and change-level notes under the openspec/ directory.
  • Use Case: When updating an OpenSpec for a new API endpoint, use this Skill to ensure that the spec.md file contains only the functional requirements, while a separate context.md file explains the business rationale, potential edge cases, and provides example requests and responses.

Quick Start

Use the openspec-context-docs skill to add context to the spec.md file located in openspec/specs/user-auth/.

Frequently Asked Questions about openspec-context-docs

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

FAQPage Schema
How do I separate normative requirements from narrative context in technical specifications?▼

To separate normative requirements from narrative context, maintain a focused `spec.md` for testable rules and place rationale, examples, and operational notes in dedicated context files within the `openspec/` directory structure.

What is the best way to document business rationale and examples for an API specification?▼

The best way to document business rationale and examples is by creating a separate `context.md` file that holds human-readable background, constraints, and failure modes, ensuring the main `spec.md` remains strictly testable.

How do I organize context documents in the openspec directory structure?▼

You organize context documents by defining specific locations for main specs, optional context splits, and change-level notes under the `openspec/` directory, keeping explanatory guidance structurally separated from normative rules.

When should I use a separate context file instead of adding notes to spec.md?▼

You should use a separate context file when you need to include purpose, rationale, constraints, or operational notes, ensuring these explanatory details do not compromise the single source of truth in `spec.md`.

Does adding narrative context to OpenSpec affect the testability of my requirements?▼

Adding narrative context does not affect testability if you enforce two-layer documentation, keeping all testable functional requirements in `spec.md` while using context files for human-readable background and guidance.

Related Skills

Explore More Software Engineering Skills→
emergent-companyemergent-company
1

openspec-sync-specs

Synchronize delta specification files into main specification files using the openspec CLI.

Official
Advanced
rafazafarrafazafar

openspec-context-docs

Organize OpenSpec docs into spec.md and context.md two-layer structure.

Community
Intermediate
thomasholknielsenthomasholknielsen
6

json-formatter

Format and validate JSON data with 2-space indentation.

Community
Basic
abudhahirabudhahir

markdown-documentation

Provide guidelines for writing technical documentation in Markdown.

Community
Basic