A skill to manage the spec registry and generate snapshots for active specs, ensuring accurate documentation.

Should I validate specs before publishing?

Yes. Run spec validate --all to verify frontmatter and formatting across all specs.

Where are the generated files located?

INDEX.md lives under changes/ and SNAPSHOT.md under specs/ as part of the standard workflow.

spec-index

npx machina-cli add skill LiorCohen/sdd/spec-index --openclaw

Files (1)

SKILL.md

2.8 KB

Spec Index Skill

Commands

The spec commands are available via the system CLI:

Generate Index

Generates changes/INDEX.md from all change spec files.

<plugin-root>/system/system-run.sh spec index --changes-dir changes/

Generate Snapshot

Generates specs/SNAPSHOT.md compiling all active specs.

<plugin-root>/system/system-run.sh spec snapshot --specs-dir specs/

Validate Spec

Validates spec frontmatter and format.

# Validate single spec
<plugin-root>/system/system-run.sh spec validate changes/2026/01/21/my-change/SPEC.md

# Validate all specs
<plugin-root>/system/system-run.sh spec validate --all --specs-dir specs/

INDEX.md Format

The index is a registry of all change specs, located at changes/INDEX.md:

# Change Index

Last updated: YYYY-MM-DD

Total: X specs (Active: Y, Deprecated: Z, Archived: W)

## Active Changes

| Change | Type | Spec | Domain | Issue | Since |
|--------|------|------|--------|-------|-------|
| User Authentication | feature | [SPEC](2025/01/01/user-auth/SPEC.md) | Identity | [PROJ-123](url) | 2025-01-01 |

## Deprecated

| Change | Type | Spec | Domain | Issue | Deprecated |
|--------|------|------|--------|-------|------------|
| Old Auth | feature | [SPEC](2025/01/15/old-auth/SPEC.md) | Identity | [PROJ-100](url) | 2025-02-01 |

## Archived

*None*

Note: Links are relative within the changes/ directory (e.g., YYYY/MM/DD/...).

SNAPSHOT.md Format

The snapshot is a compiled view of current product state:

# Product Snapshot

Generated: YYYY-MM-DD

This document represents the current active state of the product by compiling all active specifications.

## By Domain

### Identity

#### User Authentication
**Spec:** [changes/2025/01/01/user-auth/SPEC.md](changes/2025/01/01/user-auth/SPEC.md)
**Issue:** [PROJ-123](url)

[Summary of change capabilities]

---

### Billing

...

Input

Schema: schemas/input.schema.json

Accepts index command and directory paths for changes and specs.

Output

Schema: schemas/output.schema.json

Returns success status and any validation errors or warnings.

Workflow

After Creating a Spec

Merge spec to main
Run <plugin-root>/system/system-run.sh spec index to update INDEX.md
Run <plugin-root>/system/system-run.sh spec snapshot to update SNAPSHOT.md
Commit the updated index and snapshot

Before Release

Run <plugin-root>/system/system-run.sh spec validate --all to ensure all specs are valid
Review SNAPSHOT.md for completeness
Verify all active specs have corresponding implementations

Source

git clone https://github.com/LiorCohen/sdd/blob/main/plugin/core/skills/spec-index/SKILL.mdView on GitHub

Overview

Spec-index maintains the registry of change specs in changes/INDEX.md and compiles a current snapshot from active specs into specs/SNAPSHOT.md. It supports validating spec frontmatter and consistency to ensure reliable release documentation. The typical workflow is to merge changes, then regenerate index and snapshot before releases.

How This Skill Works

The skill scans change specs under changes/ and active specs under specs/, updates the registry index, and builds a consolidated snapshot reflecting the current product state. It uses system-run.sh commands to generate INDEX.md and SNAPSHOT.md and a validate command to check format and frontmatter correctness.

When to Use It

After creating or merging change specs to main
Before a release to ensure docs reflect current specs
During an audit of active vs deprecated specs
When regenerating documentation after changes
To validate spec formatting across the repository

Quick Start

Step 1: Merge the new or updated spec into main
Step 2: Run <plugin-root>/system/system-run.sh spec index to update INDEX.md
Step 3: Run <plugin-root>/system/system-run.sh spec snapshot to update SNAPSHOT.md

Best Practices

Run spec index after merging or updating specs
Run spec snapshot to keep the snapshot in sync with the index
Validate all specs (--all) before releasing
Maintain consistent formatting in changes/INDEX.md
Ensure all active specs have corresponding implementations

Example Use Cases

After merging a new feature spec, regenerate changes/INDEX.md and specs/SNAPSHOT.md to reflect the update.
During release planning, validate all specs to catch formatting or frontmatter issues.
Review the Active Changes table in INDEX.md to confirm accuracy.
Check that SNAPSHOT.md lists all currently active specs by domain.
Archive deprecated specs and verify they appear under Deprecated in INDEX.md.

Frequently Asked Questions

Add this skill to your agents