home / skills / anton-abyzov / specweave / update-instructions

update-instructions skill

/plugins/specweave/skills/update-instructions

This skill smart-merges CLAUDE.md and AGENTS.md by preserving user content while updating SpecWeave sections after refreshes or upgrades.

npx playbooks add skill anton-abyzov/specweave --skill update-instructions

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.0 KB

---
name: update-instructions
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.
---

# 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

Overview

This skill performs a smart merge for CLAUDE.md and AGENTS.md instruction files, preserving any user customizations while updating SpecWeave-managed sections. It is designed for use after plugin refreshes, version upgrades, or whenever instruction files need synchronization with the latest SpecWeave templates. The goal is to keep SW sections current without overwriting user content.

How this skill works

The skill reads existing instruction files, detects SpecWeave-managed markers (SW:META and SW:SECTION blocks), and parses template content. It replaces or inserts SW sections from the latest templates while preserving any content between or after those sections that was authored by users. Finally, it writes the merged result back to the file, handling fresh installs, legacy files, and already-marked files appropriately.

When to use it

After running specweave refresh-marketplace or similar refresh commands
Following a SpecWeave version upgrade (e.g., npm update -g specweave)
When CLAUDE.md or AGENTS.md appear outdated or missing SW sections
Before releasing or deploying agents to ensure instruction files match current specs
When syncing repo instruction files across team environments

Best practices

Commit current instruction files before running the update to allow easy rollback
Keep custom content outside SW-managed markers or between SW sections to guarantee preservation
Review merged output in a pull request to confirm template updates and custom content placement
Use the CLI npx specweave update-instructions in CI jobs after plugin or template updates
Maintain updated template versions in the project to control which SW content is applied

Example use cases

A developer upgrades SpecWeave and runs the skill to update CLAUDE.md while retaining team notes
CI pipeline refreshes AGENTS.md templates across multiple repos without overwriting local customizations
Onboarding scripts generate instruction files for new agents and append existing project-specific guidance
Fixing an older repository that lacks SW markers by prepending new SW content and leaving legacy text intact
Automated maintenance that keeps instruction files aligned with framework features before release

FAQ

Will my manual edits be overwritten?

No. Any content outside or between SW-managed markers is preserved. Only SW sections are replaced with template updates.

What happens if a file has no SW markers?

The skill prepends new SW content and preserves the original file below a separator so nothing is lost.

Can I run this in CI?

Yes. Running npx specweave update-instructions in CI after package or plugin updates ensures instruction files stay synchronized.