skills.rest
open-mercato
open-mercatoOFFICIAL
Explore all skills by this author →
WebsiteGitHub

om-fix-specs

Normalizes legacy spec filenames to the date-plus-slug convention and updates references.

1.7k|382|Updated Sep 10, 2025
Search Tags:#Python#Markdown#spec files#link updating#Repository Maintenance#filename normalization#rename script
One-click install
npx skills add https://github.com/open-mercato/open-mercato --skill om-fix-specs
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: om-fix-specs
Source: https://github.com/open-mercato/open-mercato/tree/main/.ai/skills/om-fix-specs
Command: npx skills add https://github.com/open-mercato/open-mercato --skill om-fix-specs

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Legacy specification files named with SPEC-* or SPEC-ENT-* prefixes break the date+slug naming convention, cause filename collisions when numeric prefixes are dropped, and leave stale links scattered across the repository after renames.

Core Features & Use Cases

  • Filename Normalization: Converts legacy SPEC-* and SPEC-ENT-* filenames into the canonical {YYYY-MM-DD}-{slug}.md format across .ai/specs and ai/specs roots.
  • Collision Resolution: Detects when two files would normalize to the same target and appends a numeric suffix to keep both files.
  • Reference Updating: Rewrites filename references in all Markdown, MDX, and text files throughout the repository so links stay valid after renames.
  • Use Case: After migrating a project to the date+slug spec convention, run the script in dry-run mode to preview planned renames, then apply them and verify no conflicts remain.

Quick Start

Ask the assistant to normalize the legacy spec filenames in the specs directories, starting with a dry run to review the planned renames before applying them.

Frequently Asked Questions about om-fix-specs

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

FAQPage Schema
How do I rename legacy SPEC files to a date-based naming convention?▼

Run the fix_spec_conflicts.py script with --dry-run to preview planned renames, then rerun with --apply to execute them. Files matching the SPEC-* or SPEC-ENT-* pattern with an embedded YYYY-MM-DD date are renamed to the date-plus-slug format.

How to fix broken links after renaming Markdown spec files?▼

The script automatically scans all .md, .mdx, and .txt files in the repository and replaces old filenames with new ones during the rename operation. This keeps cross-references valid without manual edits.

What happens when two spec files would get the same filename?▼

When two files normalize to the same target name, the first file keeps the desired name and subsequent files receive a numeric suffix like -2 or -3 appended to the slug. This prevents accidental overwrites.

Why are some spec files skipped during normalization?▼

Files without an embedded YYYY-MM-DD date segment in their filename are skipped because the target date-plus-slug name cannot be derived. These files must be renamed manually.

Can I preview spec renames before applying them?▼

Yes, run the script with --dry-run, which is also the default behavior. It prints every planned source-to-target rename and counts reference updates without modifying any files.

Related Skills

Explore More Software Engineering Skills→
GamezarGamezar

git-load-issues

Fetch GitHub repository issues and save them as markdown files.

Community
Intermediate
thisisqubikathisisqubika

repo-fanout-pr

Create commits and cross-linked pull requests across multiple repositories.

Official
Advanced
doctordukedoctorduke

markdown-formatter

Lints and repairs Markdown filesGitHub-style, including accessibility and formatting checks.

Official
Basic
paulchiupaulchiu
3

dated-doc-renamer

Rename files to yyyy-mm-dd Title.md format using git mv.

Community
Intermediate