AI Rules Sync

English | 中文 | 📖 Documentation

AI Rules Sync (AIS) — Install, compose, update, and publish native agent assets from multiple Git repositories across all your projects.

AIS is an asset federation toolkit, not a format converter. It keeps your files exactly as they are — skills, rules, commands, agents — and syncs them via symbolic links across every project you work on. Edit once, update everywhere.

How AIS is Different

AIS is complementary to format-conversion tools. If you also need cross-tool format conversion, you can use AIS for asset management and another tool for generation — they solve different problems.

Supports: Cursor (rules, commands, skills, subagents), GitHub Copilot (instructions, prompts, skills, agents), Claude Code (rules, skills, subagents, CLAUDE.md), Trae (rules, skills), OpenCode (commands, skills, agents, tools), Codex (rules, skills, AGENTS.md), Gemini CLI (commands, skills, agents, GEMINI.md), Windsurf (rules, skills), Cline (rules, skills), Warp (rules via AGENTS.md, skills), and universal AGENTS.md. Also supports User Mode for personal AI config files.

Installation

Via npm (Recommended)

npm install -g ai-rules-sync

Via Homebrew (macOS only)

brew tap lbb00/ai-rules-sync https://github.com/lbb00/ai-rules-sync
brew install ais

Verify:

ais --version

Optional: Enable tab completion

ais completion install

Quick Start

Use assets from a repository

cd your-project

# Add a rule (specify repository URL the first time)
ais cursor add react -t https://github.com/your-org/rules-repo.git

# After first use, omit -t
ais cursor add vue
ais copilot instructions add coding-standards
ais claude skills add code-review

Share your existing assets

# Import a rule from your project into the repository
ais cursor rules import my-custom-rule

# Optionally push to remote
ais cursor rules import my-rule --push

Restore assets (team onboarding / CI)

# Restore all assets from ai-rules-sync.json
ais install

User-level sync (personal AI configs)

# Sync personal configs to $HOME
ais claude md add CLAUDE --user
ais gemini md add GEMINI --user

# Restore on a new machine
ais user install

Supported Tools

This table is generated from docs/supported-tools.json via npm run docs:sync-tools.

📋 Full directory reference — source paths, modes, suffixes, and documentation links.

Core Concepts

How It Works

Git Repository                    Global Cache                    Your Projects
┌─────────────────┐     clone     ┌──────────────────┐  symlink  ┌──────────┐
│ .claude/skills/ │ ───────────→  │ ~/.config/       │ ────────→ │ projectA │
│ .cursor/rules/  │               │ ai-rules-sync/   │ ────────→ │ projectB │
│ .github/inst... │               │ repos/           │ ────────→ │ projectC │
└─────────────────┘               └──────────────────┘           └──────────┘

1. Clone — AIS clones your asset repositories to a global cache (~/.config/ai-rules-sync/repos/)
2. Symlink — Each project gets symbolic links pointing into the cache
3. Update — When you pull changes in the repo, every project sees them instantly

Three Configuration Layers

Three Core Operations

Basic Usage

Setup a Repository

# Use an existing remote repository
ais use https://github.com/your-org/rules-repo.git

# Use a local path (for development / testing)
ais use ~/my-rules-repo

# List all configured repositories
ais ls

# Switch between repositories
ais use company-rules
ais use personal-rules

Add Assets to Your Project

cd your-project

# First time: specify repository
ais cursor add react -t https://github.com/org/rules.git

# Subsequent adds (uses current repository)
ais cursor add vue
ais cursor add typescript

# Add with alias (different name in project)
ais cursor add react react-18

# Add from a different repository
ais cursor add coding-standards -t company-rules

# Add as private (saved to ai-rules-sync.local.json)
ais cursor add company-secrets --local

# Add to custom target directory (monorepo)
ais cursor add my-rule -d packages/frontend/.cursor/rules

Import Existing Assets

# Import a rule from your project into the repository
ais cursor rules import my-custom-rule

# Import with custom commit message
ais cursor rules import my-rule -m "Add custom rule"

# Import and push to remote
ais cursor rules import my-rule --push

# Force overwrite if exists in repository
ais cursor rules import my-rule --force

Remove Assets

ais cursor rm react
ais cursor commands rm deploy
ais cursor skills rm code-review

Install from Configuration

# Clone project and restore all assets
git clone https://github.com/team/project.git
cd project
ais install

# Install all entries for a specific tool
ais cursor install
ais claude install

Discover and Install All

# Install everything from current repository
ais add-all

# Install all Cursor rules
ais cursor add-all

# Preview before installing
ais add-all --dry-run

# Filter by tool
ais add-all --tools cursor,copilot

# Interactive mode
ais cursor add-all --interactive

Tool-Specific Commands

Cursor

ais cursor add react                 # Rule
ais cursor commands add deploy       # Command
ais cursor skills add code-review    # Skill
ais cursor agents add code-analyzer  # Subagent

GitHub Copilot

ais copilot instructions add coding-style
ais copilot prompts add generate-tests
ais copilot skills add web-scraping
ais copilot agents add code-reviewer

Claude Code

ais claude rules add general
ais claude skills add code-review
ais claude agents add debugger
ais claude md add CLAUDE             # CLAUDE.md (project)
ais claude md add CLAUDE --user      # CLAUDE.md (personal)

Codex

ais codex rules add default
ais codex skills add code-assistant
ais codex md add AGENTS --user       # ~/.codex/AGENTS.md

Gemini CLI

ais gemini commands add deploy-docs
ais gemini skills add code-review
ais gemini agents add code-analyzer
ais gemini md add GEMINI --user      # ~/.gemini/GEMINI.md

Other Tools

ais trae rules add project-rules
ais opencode agents add code-reviewer
ais opencode tools add project-analyzer
ais windsurf add project-style
ais windsurf skills add deploy-staging
ais cline add coding
ais cline skills add release-checklist
ais warp skills add my-skill
ais agents-md add .                  # Universal AGENTS.md

Advanced Features

Multiple Repositories

ais cursor add coding-standards -t company-rules
ais cursor add react-best-practices -t https://github.com/community/rules.git
ais cursor add my-utils -t personal-rules

User Mode (Personal AI Config Files)

ais claude md add CLAUDE --user      # → ~/.claude/CLAUDE.md
ais gemini md add GEMINI --user      # → ~/.gemini/GEMINI.md
ais codex md add AGENTS --user       # → ~/.codex/AGENTS.md
ais cursor rules add my-style --user

# Restore on a new machine
ais user install

Dotfiles integration:

ais config user set ~/dotfiles/ai-rules-sync/user.json
ais user install

Repository Lifecycle

# Check whether repositories are behind upstream
ais check

# Preview updates without pulling
ais update --dry-run

# Pull updates and reinstall entries
ais update

# Initialize a rules repository template
ais init

Git Commands

ais git status
ais git pull
ais git push
ais git log --oneline
ais git status -t company-rules

Custom Source Directories

For third-party repositories with non-standard structure:

# CLI parameters (temporary)
ais cursor rules add-all -s custom/rules

# Persistent configuration
ais config repo set-source third-party cursor.rules custom/rules
ais config repo show third-party

Custom Target Directories

# Monorepo: different packages
ais cursor add react-rules frontend-rules -d packages/frontend/.cursor/rules
ais cursor add node-rules backend-rules -d packages/backend/.cursor/rules

Tab Completion

ais completion install
ais cursor add <Tab>              # Lists available rules
ais cursor commands add <Tab>     # Lists available commands

Configuration Reference

ai-rules-sync.json

{
  "version": 1,
  "cursor": {
    "rules": {
      "react": "https://github.com/user/repo.git",
      "react-v2": {
        "url": "https://github.com/user/another-repo.git",
        "rule": "react"
      }
    },
    "commands": { "deploy-docs": "https://github.com/user/repo.git" },
    "skills":   { "code-review": "https://github.com/user/repo.git" },
    "agents":   { "code-analyzer": "https://github.com/user/repo.git" }
  },
  "claude": {
    "rules":  { "general": "https://github.com/user/repo.git" },
    "skills": { "code-review": "https://github.com/user/repo.git" },
    "agents": { "debugger": "https://github.com/user/repo.git" },
    "md":     { "CLAUDE": "https://github.com/user/repo.git" }
  }
}

Repository Config (ai-rules-sync.json in rules repo)

{
  "version": 1,
  "rootPath": "src",
  "sourceDir": {
    "cursor": { "rules": ".cursor/rules", "commands": ".cursor/commands" },
    "claude": { "skills": ".claude/skills", "rules": ".claude/rules" },
    "*": { "skills": "common/skills" }
  }
}

Entry Formats

Architecture

CLI (commander.js)
    ↓
Adapter Registry (34 adapters, 11 tools)
    ↓
dotany — generic dotfile management layer
    ├── SourceResolver (GitRepoSource)
    ├── ManifestStore (ai-rules-sync.json)
    └── DotfileManager (add, remove, apply, diff, status, import)
    ↓
Sync Engine (symlink creation, ignore management)
    ↓
Config Layer (global config, project config, user config)

Learn More

📖 Full documentation: https://lbb00.github.io/ai-rules-sync/

• Getting Started
• Project-Level Sync
• User Global-Level Sync
• Multiple Repositories
• CLI Reference
• Configuration Reference

Links

• Documentation: https://lbb00.github.io/ai-rules-sync/
• Issues: https://github.com/lbb00/ai-rules-sync/issues
• NPM: https://www.npmjs.com/package/ai-rules-sync

License

Unlicense - Free to use, modify, and distribute.