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.

⭐17stars🔀3forks📁View on GitHub🕐Updated Jan 3, 2026

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.
nameupdate-instructions
descriptionUpdate 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

  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