Features

aps is a manifest-driven, CLI tool for syncing agentic assets (Cursor rules, Agent Skills, and AGENTS.md files) from sources like git or your filesystem in your project folders.

• Declarative manifest-driven sync - Define your agentic assets in a YAML manifest
• Composable AGENTS.md - Merge multiple AGENTS.md files from local or remote sources into one
• Safe installs - Automatic conflict detection and backup creation
• Deterministic lockfile - Idempotent syncs that only update when needed

Installation

Quick Install (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/westonplatter/agentic-prompt-sync/main/install.sh | sh

This downloads the latest release and installs to ~/.local/bin. Set APS_INSTALL_DIR to customize:

APS_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/westonplatter/agentic-prompt-sync/main/install.sh | sh

Download Binary

Pre-built binaries for all platforms are available on the Releases page.

Cargo Install

If you have Rust installed:

cargo install aps

Build from Source

git clone https://github.com/westonplatter/agentic-prompt-sync.git
cd agentic-prompt-sync
cargo build --release
# Binary at target/release/aps

Getting Started

Quick Start

1. Initialize a manifest in your project:

aps init

This creates a aps.yaml manifest file with an example entry.

2. Edit the manifest to define your assets:

entries:
  - id: my-agents
    kind: agents_md
    source:
      type: filesystem
      root: $HOME
      path: personal-generic-AGENTS.md
    dest: ./AGENTS.md

3. Sync and install your assets:

aps sync

4. Check status of synced assets:

aps status

Commands

Common Options

• --verbose - Enable verbose logging
• --manifest <path> - Specify manifest file path (default: aps.yaml)

Sync Options

• --yes - Non-interactive mode, automatically confirm overwrites
• --dry-run - Preview changes without applying them
• --only <id> - Only sync specific entry by ID

Sync Behavior

When you run aps sync:

1. Entries are synced - Each entry in aps.yaml is installed to its destination
2. Stale entries are cleaned - Entries in the lockfile that no longer exist in aps.yaml are automatically removed
3. Lockfile is saved - The updated lockfile is written to disk

Note: Stale entry cleanup only happens during a full sync. When using --only <id> to sync specific entries, other lockfile entries are preserved.

Configuration

Manifest File (aps.yaml)

entries:
  # Single AGENTS.md file from one source
  - id: my-agents
    kind: agents_md
    source:
      type: filesystem
      root: $HOME
      path: AGENTS-generic.md
    dest: ./AGENTS-simple.md

  # Composite AGENTS.md - merge multiple markdown files into one
  - id: composite-agents
    kind: composite_agents_md
    sources:
      - type: filesystem
        root: $HOME/agents
        path: AGENT.python.md
      - type: filesystem
        root: $HOME/agents
        path: AGENT.docker.md
      - type: git
        repo: https://github.com/apache/airflow.git
        ref: main
        path: AGENTS.md
    dest: ./AGENTS.md

  # Pull in Agent Skills from a public git repo
  - id: anthropic-skills
    kind: agent_skill
    source:
      type: git
      repo: git@github.com:anthropics/skills.git
      ref: main
      path: skills
    include:
      - pdf
      - skill-creation
    dest: ./.claude/skills/

  # Pull Cursor Rules from a private git repo
  - id: personal-rules
    kind: cursor_rules
    source:
      type: git
      repo: git@github.com:your-username/dotfiles.git
      ref: main
      path: .cursor/rules
    dest: ./.cursor/rules/

  # Pull in more Cursor Rules from a local file system
  - id: company-rules
    kind: cursor_rules
    source:
      type: filesystem
      root: $HOME/work/acme-corp/internal-prompts
      path: rules
    dest: ./.cursor/rules/

Asset Types

Source Types

Shell Variable Expansion: Path values in root and path fields support shell variable expansion (e.g., $HOME, $USER). This makes manifests portable across different machines and users.

Composite AGENTS.md

The composite_agents_md kind allows you to merge multiple markdown files into a single AGENTS.md file. This is useful when you want to organize agent definitions across separate files (e.g., by language or framework) and combine them at sync time.

entries:
  - id: my-composite-agents
    kind: composite_agents_md
    sources:
      # Local filesystem sources
      - type: filesystem
        root: $HOME/agents-md-partials
        path: AGENT.docker.md
      # Remote git sources
      - type: git
        repo: https://github.com/westonplatter/agentically.git
        ref: main
        path: agents-md-partials/AGENTS.python.md
    dest: ./AGENTS.md

Key features:

• Mixed sources: Combine local filesystem and remote git sources
• Order preserved: Files are merged in the order specified in sources
• Auto-generated header: Output includes a comment indicating it was composed by aps

Lockfile (aps.lock.yaml)

The lockfile tracks installed assets and is automatically created/updated by aps sync. This file should be committed to version control to ensure reproducible installations across your team. It stores:

• Source information
• Destination paths
• Last update timestamp
• Content checksum (SHA256)

Environment Variables Are Preserved: Unlike other package managers (npm, uv, bundler) that expand environment variables to concrete paths, aps preserves shell variables like $HOME in the lockfile. This makes lockfiles portable across different machines and users who have the same relative directory structure.

Examples

Non-interactive sync for CI/CD

aps sync --yes

Validate manifest before sync

aps validate --strict

Development

Build

cargo build           # Debug build
cargo build --release # Release build

Run tests

cargo test

Linting

This project uses Trunk for linting and code quality checks.

trunk check       # Run linters on modified files
trunk fmt         # Format code
trunk check list  # View available linters

Run with verbose logging

cargo run -- --verbose sync

Inspiration

Built based on inspiration from these other projects,

• rule-tool

License

See LICENSE for details.