Skip to main content

​
Overview

The /update-nanoclaw skill helps you pull updates from the upstream NanoClaw repository into your customized fork without losing your modifications. It handles merge conflicts intelligently and validates the result.

​
When to Use

Your NanoClaw fork drifts from upstream as you customize it. Run this skill when:
  • A new NanoClaw version is released
  • You want new upstream features
  • Security updates are available
  • Bug fixes are published

​
How It Works

​
1. Preflight Checks

  • Verifies clean working tree (git status --porcelain)
  • Adds upstream remote if missing (defaults to https://github.com/qwibitai/nanoclaw.git)
  • Detects upstream branch name (main or master)

​
2. Backup

Creates timestamped backup before any changes:
  • Branch: backup/pre-update-<hash>-<timestamp>
  • Tag: pre-update-<hash>-<timestamp>

​
3. Preview

Shows upstream changes since your last sync: 
git log --oneline upstream/main..HEAD
git diff --stat upstream/main..HEAD
Groups changed files into categories:
  • Skills (.claude/skills/) - Unlikely to conflict
  • Source (src/) - May conflict if you modified same files
  • Build/config - Review needed

​
4. Update Paths

You choose: 
git merge upstream/main
Resolves all conflicts in one pass. Recommended for most users.

​
5. Conflict Resolution

  • Dry-run shows which files would conflict
  • Opens only conflicted files
  • Resolves conflict markers
  • Keeps your local customizations intact

​
6. Validation

Runs after merge: 
npm run build
npm test

​
7. Breaking Changes Check

Reads CHANGELOG.md for [BREAKING] entries. If found:
  • Shows each breaking change
  • Offers to run recommended migration skill

​
How to Apply

1

Run the command

/update-nanoclaw
2

Review preview

Claude shows:
  • Number of upstream commits
  • Changed files grouped by category
  • Potential conflicts
3

Choose update strategy

Select merge, cherry-pick, rebase, or abort.
4

Resolve conflicts (if any)

Claude opens conflicted files and helps resolve them.
5

Verify

Build and tests run automatically.

​
Token Usage

This skill is optimized for low token usage:
  • Only opens files with actual conflicts
  • Uses git log and git diff for summaries
  • Does not scan or refactor unrelated code

​
Rollback

If something goes wrong, reset to the backup: 
git reset --hard pre-update-<hash>-<timestamp>
The skill prints the exact tag name at the end of each run. Alternatively, checkout the backup branch: 
git checkout backup/pre-update-<hash>-<timestamp>

​
Common Scenarios

If upstream changes don’t overlap with your customizations:
  1. Merge completes automatically
  2. Build and tests pass
  3. You’re updated!
If you modified the same files as upstream:
  1. Dry-run shows conflicted files
  2. Claude opens each file
  3. Resolves <<<<<<< HEAD markers
  4. Keeps your customizations
  5. Runs validation
If upstream introduces breaking changes:
  1. CHANGELOG.md shows [BREAKING] entries
  2. Claude explains each change
  3. Offers to run migration skills (e.g., /migrate-to-v2)
  4. You apply migrations
  5. Re-validate

​
Best Practices

Update Regularly

Update monthly to avoid large drift from upstream

Test After Update

Send test messages to each channel to verify functionality

Read Changelog

Review CHANGELOG.md before merging to understand what’s changing

Keep Backups

Don’t delete backup tags until you’ve verified the update

Customization

How to customize NanoClaw

Skills System

Understanding the skills architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us