update-instructions

使用智能合并更新CLAUDE.md和AGENTS.md指令文件。在更新SpecWeave部分时保留用户自定义。在插件刷新、版本升级或指令文件需要同步后使用。激活条件:更新指令、刷新claude.md、合并agents.md、同步指令文件、升级specweave配置。

📖 中文导读:使用智能合并更新CLAUDE.md和AGENTS.md指令文件。在更新SpecWeave部分时保留用户自定义。在插件刷新、版本升级或指令文件需要同步后使用。激活条件:更新指令、刷新claude.md、合并agents.md、同步指令文件、升级specweave配置。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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

  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