promote-spec

Promote a flat spec into a folder spec using a CLI command.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/hodor/claude-compass --skill promote-spec-hodor
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: promote-spec
Source: https://github.com/hodor/claude-compass/tree/main/plugin/skills/promote-spec
Command: npx skills add https://github.com/hodor/claude-compass --skill promote-spec-hodor

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

This Skill helps manage the growth and organization of specifications in a project, ensuring they remain maintainable and structured as they evolve.

Core Features & Use Cases

  • Spec Promotion: Promote a flat spec into a folder spec, enhancing organization and scalability.
  • Automated Move: The CLI automates the move of the spec, while the skill determines when and how to promote.
  • Authoring Guidance: Guides the authoring of child specs within the new folder structure.
  • Use Case: When a spec grows too large or complex, this skill helps transform it into a folder spec, keeping the project organized and maintainable.

Quick Start

Run the 'compass promote' command with the spec name to promote a spec into a folder spec.

Frequently Asked Questions about promote-spec

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

FAQPage Schema
How do I refactor a large project spec into a folder structure?

To refactor a large project spec into a folder structure, you can promote the flat specification into a folder spec using an automated CLI command. This moves the spec and guides the authoring of structured child specs to enhance project maintainability.

When should I promote a flat spec to a folder spec?

You should promote a flat spec to a folder spec when the specification grows too large or complex for a single file. Promoting it transforms the flat structure into an organized folder, keeping the project maintainable as it evolves.

What is the best way to manage spec growth and maintain project organization?

The best way to manage spec growth is to promote flat specs into folder specs once they become overly complex. This automated process restructures the specifications into organized folders with guided child spec authoring.

Does promoting a spec require manual file movement?

Promoting a spec does not require manual file movement because the CLI command automates the move. The skill itself determines when and how to promote, while guiding the authoring of the subsequent child specs within the new folder.

What are the limitations of using an automated spec promotion process?

The limitation of automated spec promotion is that it requires authoring child specs manually after the move. Additionally, the skill determines when to promote, meaning it only triggers when a spec reaches a certain threshold of complexity.