Update Instructions Skill

Smart merge for CLAUDE.md and AGENTS.md instruction files.

What It Does

1. Reads existing instruction files (if present)
2. Parses SW-managed sections (marked with <!-- SW:SECTION:X -->)
3. Preserves user content (anything between or after SW sections)
4. Updates SW sections with latest template content
5. Writes merged result back to file

When to Use

• After running specweave refresh-marketplace
• After upgrading SpecWeave version (npm update -g specweave)
• When CLAUDE.md or AGENTS.md seem outdated
• To sync instruction files with latest framework features

Usage

/sw:update-instructions

Or via CLI:

npx specweave update-instructions

How Merge Works

Fresh Install (no existing file)

Creates new file with all SW sections + meta header

Legacy File (no SW markers)

Prepends new SW content, preserves original below separator

Marked File (has SW markers)

Updates SW sections in-place, preserves user content between sections

Section Format

Template sections (in .template files):

<!-- SECTION:rules required -->
## Rules
Content here...
<!-- /SECTION -->

Generated sections (in output files):

<!-- SW:META template="claude" version="1.0.0" sections="header,rules,..." -->

<!-- SW:SECTION:header version="1.0.0" -->
Content...
<!-- SW:END:header -->

User Customization

Add custom content between SW sections or after the last section:

<!-- SW:END:docs -->

## My Custom Section

This will be preserved during updates!

Files Affected

• CLAUDE.md – Claude Code instruction file
• AGENTS.md – Generic AI tool instruction file

Project-Specific Learnings

Before starting work, check for project-specific learnings:

# Check if skill memory exists for this skill
cat .specweave/skill-memories/update-instructions.md 2>/dev/null || echo "No project learnings yet"

Project learnings are automatically captured by the reflection system when corrections or patterns are identified during development. These learnings help you understand project-specific conventions and past decisions.