AgentSkillsCN

sw:update-instructions

针对 CLAUDE.md 和 AGENTS.md 指令文件进行智能合并，在更新 SpecWeave 部分的同时，完整保留用户的自定义配置。在插件刷新、版本升级，或需要同步指令文件时，可优先选用此功能。它能精准解析由 SW 管理的各部分内容，并确保用户原有内容不被覆盖。

SKILL.md
--- frontmatter
description: Smart merge for CLAUDE.md and AGENTS.md instruction files that preserves user customizations while updating SpecWeave sections. Use after plugin refresh, version upgrade, or when instruction files need sync. Parses SW-managed sections and preserves user content.
user-invocable: false

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

code
/sw:update-instructions

Or via CLI:

bash
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):

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

Generated sections (in output files):

markdown
<!-- 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:

markdown
<!-- 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:

bash
# 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.