sdd-refactor-artifact

Reorganizes existing SDD artifacts into canonical template format while preserving all content.

Updated Aug 2, 2026
One-click install
npx skills add https://github.com/phm-aguiar/test_documentacao --skill sdd-refactor-artifact-phm-aguiar
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: sdd-refactor-artifact
Source: https://github.com/phm-aguiar/test_documentacao/tree/main/.claude/skills/sdd-refactor-artifact
Command: npx skills add https://github.com/phm-aguiar/test_documentacao --skill sdd-refactor-artifact-phm-aguiar

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes assets (resource) components.

What problem does it solve? SDD artifacts like spec.md, plan.md, and tasks.md often drift away from the canonical template structure over time, making them inconsistent and harder for AI agents to consume. This Skill normalizes existing artifacts to the canonical format without losing any original content. ## Core Features & Use Cases - Canonical Reorganization: Maps existing sections of spec.md, plan.md, tasks.md, CLAUDE.md, and llms.txt to their canonical template structures. - Content Preservation: Guarantees no original content is discarded; unmatched content moves to a Notes section and placeholders like {{...}} stay intact. - Confirmation-First Workflow: Always presents a diff summary of renamed, moved, and added sections and requires user approval before writing changes. - Use Case: You inherited a project where spec.md uses custom headings and plan.md mixes architecture decisions with task lists. Run this Skill to normalize both files to the canonical SDD templates while keeping every sentence of the original. ## Quick Start Ask the assistant to refactor the artifact at specs/features/001-login/spec.md into the canonical SDD format and show the diff before saving.

Frequently Asked Questions about sdd-refactor-artifact

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

FAQPage Schema
How do I reformat an existing spec.md to the canonical SDD template?▼

Point the Skill at your spec.md file path. It reads the canonical template from its assets, maps your existing sections to canonical ones, shows a diff of the changes, and only saves after you confirm.

What is the difference between sdd-refactor-artifact and sdd-generate-plan?▼

sdd-refactor-artifact normalizes artifacts that already exist by reorganizing their sections. sdd-generate-plan and sdd-generate-tasks create plan.md or tasks.md from scratch when no file exists yet.

Does refactoring an SDD artifact lose any original content?▼

No. The Skill enforces total content preservation: every original section appears in the output, unmatched content moves to a Notes section, and placeholders like {{...}} remain exactly as written.

Can it refactor CLAUDE.md without changing unrelated sections?▼

Yes. For CLAUDE.md only the SDD Workflow section is refactored to the canonical structure; all other sections of the file remain byte-identical to the original.

What happens if my artifact already follows the canonical format?▼

The Skill is idempotent. If the file already conforms to the template, it reports that no changes are needed and does not modify the file.