# Update Instructions

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

- Skill: `majiayu000/update-instructions` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/update-instructions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/update-instructions/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, Productivity
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/update-instructions

---


# 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:
```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.