Agent skill

update-rules

Sync technical rules between projects - bidirectional copy with category filtering. TRIGGER when: user wants to sync rules ("update rules from X", "sync rules", "pull rules from framework", "push rules to project"). DO NOT TRIGGER when: user wants to update pillars/skills/workflow (use respective update-* skills), or just wants to read rule docs.

View SKILL.md on GitHub Repository

Stars 163

Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/update-rules

SKILL.md

Update Rules - Technical Rules Synchronization

Sync technical rule documentation between projects bidirectionally with profile-aware filtering (v2.2.0+).

Overview

This skill synchronizes technical rules (.claude/rules/) between projects:

What it does:

Scans source and target projects for rules
Filters by profile - syncs only rules relevant to tech stack (recommended)
Compares rules to detect new/updated content
Shows detailed diff preview with filter summary
Syncs rules with confirmation
Validates profile compliance
Reports what was synced

Why it's needed: Framework rule updates need to propagate across projects with precision. Category-based sync causes 30-50% rule bloat (e.g., Tauri rules in web apps). Profile-aware filtering ensures zero incorrect rules by syncing only what's relevant to each project's tech stack.

When to use:

Monthly framework upgrades
Propagating best practices
Cross-project learning
Initial project setup

Workflow

Step 1: Create Todo List

Initialize sync tracking using TaskCreate:

Task #1: Validate source and target paths
Task #2: Scan rules in both projects (blocked by #1)
Task #3: Compare rules by category (blocked by #2)
Task #4: Show diff preview (blocked by #3)
Task #5: Execute sync with confirmation (blocked by #4)
Task #6: Report sync results (blocked by #5)

After creating tasks, proceed with sync execution.

Rule Categories

.claude/rules/
├── core/                    # Workflow, naming, debugging (7 rules)
├── architecture/            # Clean architecture, layers (7 rules)
├── languages/               # TypeScript, Python, Go (3 rules)
├── frontend/                # React, state management (6 rules)
├── backend/                 # Lambda, API design (5 rules)
├── infrastructure/          # AWS CDK, secrets (10 rules)
└── development/             # Performance, security (2 rules)

Sync Modes

1. Pull Rules (--from)

Pull rules from source project to current project:

bash

/update-rules --from ~/dev/ai-dev
/update-rules --from ~/dev/ai-dev --dry-run
/update-rules --from ~/dev/ai-dev --categories core,architecture

What happens:

Scan source: <source>/.claude/rules/
Scan current: .claude/rules/
Compare by category
Detect: NEW, NEWER, SAME, OLDER
Show analysis table
Confirm and copy updated rules

2. Push Rules (--to)

Push rules from current project to target project:

bash

/update-rules --to ~/projects/my-app
/update-rules --to ~/projects/my-app --dry-run
/update-rules --to ~/projects/my-app --categories backend,infrastructure

What happens:

Scan current project rules
Scan target project rules
Compare by category
Show what will be pushed
Confirm and copy to target

3. Dry Run Mode (--dry-run)

Preview changes without applying:

bash

/update-rules --from ~/dev/ai-dev --dry-run

Output:

Shows analysis table by category
Reports what would be synced
No confirmation required
No actual changes made

4. Profile-Based Sync (--profile) - RECOMMENDED

New in v2.2.0: Sync rules based on project profile with precise filtering.

Sync only rules relevant to project's tech stack:

bash

/update-rules --from ~/dev/ai-dev --to ~/dev/u-safe --profile tauri
/update-rules --from ~/dev/ai-dev --to ~/dev/buffer --profile nextjs-aws
/update-rules --from ~/dev/ai-dev --profile tauri-aws  # Auto-detects target from pwd

How it works:

Reads profile definition from framework/profiles/<profile>.json
Applies rules.include whitelist (exact rules needed)
Applies rules.exclude patterns (rules to skip)
Syncs ONLY relevant rules for that tech stack

Benefits:

✅ Precise rule sets (zero bloat)
✅ No incorrect rules (e.g., no Tauri in web apps, no AWS in desktop apps)
✅ Profile compliance validation
✅ Better Claude Code context management

Supported Profiles:

tauri - Desktop apps (Tauri + React): 23 rules
tauri-aws - Desktop + cloud backend: TBD rules
nextjs-aws - Full-stack web (Next.js + AWS): 30 rules

Example Results (from Issue #162):

Before:
  u-safe (tauri): 46 rules (bloated with AWS/Lambda rules)
  buffer (nextjs-aws): 43 rules (bloated with Tauri rules)

After:
  u-safe (tauri): 23 rules ✅ (50% reduction)
  buffer (nextjs-aws): 30 rules ✅ (30% reduction)

Impact: 100% profile compliance, zero incorrect rules

Profile Definition Example (framework/profiles/tauri.json):

json

{
  "name": "tauri",
  "pillars": ["A", "B", "K", "L"],
  "rules": {
    "include": [
      // Core (7 rules)
      "workflow", "naming", "debugging", "docs",
      "memory-management", "memory-protection", "planning-context",

      // Architecture (6 rules)
      "clean-architecture", "dependency-rule", "service-layer",
      "headless", "adapters", "identity",

      // Languages (3 rules)
      "typescript-esm", "typescript-strict", "typescript-nominal-types",

      // Frontend (4 rules)
      "design-system", "zustand-hooks", "views", "css",

      // Infrastructure - Tauri specific (3 rules)
      "tauri-stack", "tauri-ipc", "tauri-security"
    ],
    "exclude": [
      "backend/lambda-*.md",      // No serverless in desktop
      "infrastructure/aws-*.md",  // No AWS in desktop
      "infrastructure/cdk-*.md"   // No CDK in desktop
    ]
  }
}

Comparison with Category Filtering:

Approach	nextjs-aws Example	Result
`--categories`	Syncs ALL rules in specified categories	43 rules (30% bloat)
`--profile`	Syncs ONLY rules in profile's include list	30 rules (100% precise)

Migration from --categories:

bash

# Old way (category-based) - causes bloat
/update-rules --to ~/dev/buffer --categories core,architecture,frontend,backend,infrastructure
# Result: 43 rules (includes irrelevant Tauri rules)

# New way (profile-based) - precise
/update-rules --to ~/dev/buffer --profile nextjs-aws
# Result: 30 rules (only relevant rules)

Troubleshooting:

bash

# Check current rule count
find .claude/rules -name "*.md" | wc -l

# Check expected count for profile
cat ~/dev/ai-dev/framework/profiles/nextjs-aws.json | jq '.rules.include | length'

# If mismatch, re-sync with profile
cd ~/dev/ai-dev
/update-rules --to ~/dev/your-project --profile <profile>

5. Category Filter (--categories) - LEGACY

Deprecated: Use --profile instead for precise filtering.

Sync rules by category (coarse-grained):

bash

/update-rules --from ~/dev/ai-dev --categories core,architecture,languages
/update-rules --to ~/projects/my-app --categories frontend,backend

Available categories:

core - Workflow, naming, debugging, docs
architecture - Clean architecture, layers, dependencies
languages - TypeScript, Python, Go
frontend - React, state, design system
backend - Lambda, saga, API design
infrastructure - AWS CDK, secrets, monitoring
development - Performance, security

Why deprecated:

❌ Too coarse-grained (syncs ALL rules in category)
❌ Causes rule bloat (30-50% extra rules)
❌ Can't exclude specific files within category
✅ Use --profile instead for precise control

6. Smart Filter (--filter-config)

Apply intelligent filtering based on tech stack configuration:

bash

# Used by /update-framework meta-skill
/update-rules --from ~/dev/ai-dev --filter-config <target>/.claude/framework-config.json

What it does:

Reads filter config from .claude/framework-config.json
Applies include/exclude patterns based on tech stack
Filters by categories, specific files, and glob patterns
Shows filter summary in analysis

Filter Configuration Format:

json

{
  "filterConfig": {
    "rules": {
      "include_categories": ["core", "architecture", "frontend", "languages"],
      "include_files": ["infrastructure/tauri-stack.md"],
      "exclude_patterns": [
        "backend/lambda-*.md",
        "infrastructure/aws-*.md",
        "infrastructure/cdk-*.md"
      ]
    }
  }
}

Filter Logic:

For each rule file:
1. Check if category in include_categories
   → Skip if not included
2. Check if file matches include_files
   → Include if matched
3. Check if file matches exclude_patterns
   → Exclude if matched (takes precedence)
4. Apply normal NEW/NEWER/SAME logic

Example - Tauri Project:

Without filter: 43 rules synced With filter: ~25 rules synced (excludes AWS/Lambda rules)

📋 Smart Filter Active (Tauri + React + No Cloud)
⏭️  Excluding: backend/lambda-* (3 files)
⏭️  Excluding: infrastructure/aws-* (5 files)
⏭️  Excluding: infrastructure/cdk-* (3 files)
✅ Including: infrastructure/tauri-stack.md

Result: 25 rules synced (18 excluded as not relevant)

Note: Typically called by /update-framework meta-skill, not directly by users.

Comparison Logic

File status detection:

For each rule file:
1. Check if exists in target
   → NEW if not found
2. Compare modification time
   → NEWER if source newer
   → OLDER if source older
3. Compare file size
   → CONFLICT if same time, different size
   → SAME if identical

Analysis output:

📊 Analysis by category:
┌────────────────┬─────┬─────┬──────┐
│ Category       │ New │ Upd │ Same │
├────────────────┼─────┼─────┼──────┤
│ core           │  0  │  1  │   6  │
│ architecture   │  0  │  2  │   5  │
│ languages      │  1  │  0  │   2  │
│ frontend       │  1  │  1  │   4  │
│ backend        │  2  │  0  │   3  │
│ infrastructure │  0  │  1  │   9  │
│ development    │  0  │  0  │   2  │
└────────────────┴─────┴─────┴──────┘

Summary:
- New rules: 4
- Updated rules: 5
- Unchanged: 33
- Total to sync: 9 rules

What Gets Synced

.claude/rules/
├── core/
│   ├── workflow.md           ✅ Synced
│   ├── naming.md             ✅ Synced
│   └── ...                   ✅ Synced
├── architecture/
│   └── ...                   ✅ Synced
├── languages/
│   └── ...                   ✅ Synced
├── frontend/
│   └── ...                   ✅ Synced
├── backend/
│   └── ...                   ✅ Synced
├── infrastructure/
│   └── ...                   ✅ Synced
└── development/
    └── ...                   ✅ Synced

.claude/
├── settings.json             ❌ Not synced (project-specific)
├── MEMORY.md                 ❌ Not synced (project-specific)
└── plans/                    ❌ Not synced (project-specific)

Usage Examples

Example 1: Profile-Based Sync (Recommended)

User says:

"update rules from framework for my tauri project"

What happens:

Detect profile from .framework-install → tauri
Load framework/profiles/tauri.json → 23 rules in include list
Scan and filter: exclude AWS/Lambda/CDK rules
Show: 23 rules to sync (with filter summary)
Confirm and sync
Report: "Synced 23 rules (tauri profile, 100% compliance)"

Before/After:

Before: 46 rules (bloated with AWS rules)
After: 23 rules (precise, zero bloat)
Reduction: 50%

Time: ~25 seconds

Example 2: Framework Upgrade with Profile

User says:

"update rules from the framework"

What happens:

Auto-detect profile from .framework-install
Apply profile filtering
Show: 5 rules to update (only relevant ones)
Confirm and sync
Report: "Updated 5 rules (nextjs-aws profile)"

Time: ~20 seconds

Example 3: Category-Based Update (Legacy - Not Recommended)

User says:

"pull only frontend and React rules from the framework"

What happens:

/update-rules --from ~/dev/ai-dev --categories frontend,languages
Scan frontend/ and languages/ categories
Show: 3 rules to update
Sync specific categories
Report: "Updated 3 frontend/language rules"

⚠️ Warning: This syncs ALL rules in categories, causing bloat. Use --profile instead.

Time: ~20 seconds

Safety Features

Pre-flight checks:

✅ Source/target paths exist
✅ Source has .claude/rules/ directory
✅ User confirmation before changes
✅ Dry-run preview available

Smart filtering:

Profile-aware filtering (whitelist-based)
Only syncs rules relevant to tech stack
Excludes incorrect rules (e.g., no AWS in desktop apps)
Clear status for each rule

Backup strategy:

bash

# Before overwrite
.claude/rules/core/workflow.md
→ .claude/rules/core/workflow.md.backup-20260306

Error Handling

Invalid Source/Target

❌ Error: Project not found

Path: ../nonexistent
Expected: ../nonexistent/.claude/rules/

Please check:
1. Path is correct
2. Project has .claude/rules/ directory
3. You have read permissions

No Rules to Update

✅ All rules are up to date!

No new or updated rules found in source.
Current project has all latest versions.

Invalid Category

❌ Error: Unknown category: invalid-category

Valid categories:
- core
- architecture
- languages
- frontend
- backend
- infrastructure
- development

Best Practices

Use profile-based sync (recommended):

bash

# Auto-detects profile from .framework-install
/update-rules --from ~/dev/ai-dev --to ~/dev/u-safe --profile tauri

# Ensures zero incorrect rules
/update-rules --from ~/dev/ai-dev --to ~/dev/buffer --profile nextjs-aws

Always dry-run first:

bash

/update-rules --from ~/dev/ai-dev --dry-run
/update-rules --from ~/dev/ai-dev

Framework as source of truth:

bash

# In projects: pull from framework with profile
/update-rules --from ~/dev/ai-dev --profile tauri

# In framework: test profile filtering
/update-rules --to ~/dev/test-project --profile nextjs-aws --dry-run

Regular updates:

bash

# Weekly/monthly routine (profile auto-detected)
/update-rules --from ~/dev/ai-dev

Integration

With other update- skills:*

bash

# Complete framework update
/update-pillars --from ~/dev/ai-dev   # 1. Pillars
/update-rules --from ~/dev/ai-dev     # 2. Rules
/update-workflow --from ~/dev/ai-dev  # 3. Workflow
/update-skills --from ~/dev/ai-dev    # 4. Skills

# Or use meta-skill
/update-framework --from ~/dev/ai-dev # All-in-one

Common workflow:

Framework upgrade → Pull Rules → Apply best practices
Project setup → Push Rules → Share knowledge

Task Management

After each sync step, update progress:

Paths validated → Update Task #1
Rules scanned → Update Task #2
Rules compared by profile → Update Task #3
Diff shown → Update Task #4
Sync executed → Update Task #5
Results reported → Update Task #6

Provides real-time visibility of sync progress.

Final Verification

Before declaring sync complete, verify:

- [ ] All 6 sync tasks completed
- [ ] Source and target paths valid
- [ ] Rules compared by profile (or category if legacy mode)
- [ ] User confirmed changes
- [ ] Files copied correctly
- [ ] Sync summary displayed with filter info

Missing items indicate incomplete sync.

Workflow Skills Requirements

This is a workflow skill and must follow the standard pattern:

TaskCreate at start - Create todo list for progress tracking
TaskUpdate during execution - Mark tasks in_progress → completed
Verification checklist - Final validation before completion

See: WORKFLOW_PATTERNS.md for complete implementation guide

Related Skills

/update-framework - Sync entire framework (calls this skill)
/update-pillars - Sync Pillars
/update-skills - Sync skills
/update-workflow - Sync workflow docs

Version: 2.1.0 Last Updated: 2026-03-12 Changelog:

v2.1.0 (2026-03-12): Sync technical rules between projects with profile-aware filtering Pattern: Tool-Reference (guides sync process) Compliance: ADR-001 Section 4 ✅

Maintainer

majiayu000 Core maintainer

Source details

Full Name: majiayu000/claude-skill-registry
Branch: main
Path in repo: skills/other/other/update-rules
License: MIT License

Featured Tools

Join Our Newsletter

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

Update Rules - Technical Rules Synchronization

Overview

Workflow

Step 1: Create Todo List

Rule Categories

Sync Modes

1. Pull Rules (--from)

2. Push Rules (--to)

3. Dry Run Mode (--dry-run)

4. Profile-Based Sync (--profile) - RECOMMENDED

5. Category Filter (--categories) - LEGACY

6. Smart Filter (--filter-config)

Comparison Logic

What Gets Synced

Usage Examples

Example 1: Profile-Based Sync (Recommended)

Example 2: Framework Upgrade with Profile

Example 3: Category-Based Update (Legacy - Not Recommended)

Safety Features

Error Handling

Invalid Source/Target

No Rules to Update

Invalid Category

Best Practices

Integration

Task Management

Final Verification

Workflow Skills Requirements

Related Skills

Recommended Agent Skills

agent-ops-spec

agent-ops-state

agent-ops-spec

agent-ops-testing

agent-ops-testing

agent-ops-state