update-instructions
Update CLAUDE.md and AGENTS.md instruction files with smart merge. Preserves user customizations while updating SpecWeave sections. Use after plugin refresh, version upgrade, or when instruction files need sync. Activates for: update instructions, refresh claude.md, merge agents.md, sync instruction files, upgrade specweave config.
When & Why to Use This Skill
The update-instructions skill provides a robust mechanism for synchronizing CLAUDE.md and AGENTS.md files using a smart merge algorithm. It allows developers to seamlessly integrate the latest SpecWeave instruction templates and framework updates into their projects while ensuring that all manual customizations and user-defined sections remain untouched, optimizing the AI agent's performance with up-to-date context.
Use Cases
- Version Upgrades: Automatically update project instruction files after upgrading SpecWeave to ensure compatibility with new agent features and improved prompt logic.
- Template Synchronization: Refresh CLAUDE.md and AGENTS.md after a marketplace update to pull in the latest best practices for AI-assisted coding and project management.
- Customization Preservation: Safely merge standardized agent rules with project-specific documentation by utilizing smart SW-managed section markers that protect user-written content.
- Legacy File Migration: Transition standard markdown instruction files into smart-managed versions by prepending new SW content while preserving original legacy notes.
| name | update-instructions |
|---|---|
| description | Update CLAUDE.md and AGENTS.md instruction files with smart merge. Preserves user customizations while updating SpecWeave sections. Use after plugin refresh, version upgrade, or when instruction files need sync. Activates for: update instructions, refresh claude.md, merge agents.md, sync instruction files, upgrade specweave config. |
Update Instructions Skill
Smart merge for CLAUDE.md and AGENTS.md instruction files.
What It Does
- Reads existing instruction files (if present)
- Parses SW-managed sections (marked with
<!-- SW:SECTION:X -->) - Preserves user content (anything between or after SW sections)
- Updates SW sections with latest template content
- 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 fileAGENTS.md- Generic AI tool instruction file