GitHub - westonplatter/agentic-prompt-sync: Compose and sync your own collection of AGENTS.md, Skills, and other agentic prompts

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)

Install or update aps using cargo

# install the latest version
cargo install aps

Or use curl,

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

# or override the install location
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.

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:

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

2. Add skills directly from GitHub URLs:

   # Add a skill from a GitHub URL - automatically syncs the skill
   aps add https://github.com/hashicorp/agent-skills/blob/main/terraform/module-generation/skills/refactor-module/SKILL.md
   
   # Or use the folder URL (SKILL.md is auto-detected)
   aps add https://github.com/hashicorp/agent-skills/tree/main/terraform/module-generation/skills/refactor-module
   

   This parses the GitHub URL, adds an entry to aps.yaml, and syncs only that skill immediately (other entries are not affected).

3. Or manually 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
   

4. Sync and install your assets:

5. Check status of synced assets:

Commands

Common Options

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

Add Options

• --id <name> - Custom entry ID (defaults to skill folder name)
• --kind <type> - Asset kind: agent-skill, cursor-rules, cursor-skills-root, agents-md (default: agent-skill)
• --no-sync - Only add to manifest, don't sync immediately

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
      # shallow: false  # full clone
    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
      # symlink: false  # copy files instead of symlinking
    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.

Filtering with include

When a source contains multiple subdirectories (e.g., a skills repo with many skills), use the include field to sync only specific ones:

- 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/

Each value in include is matched against subdirectory names within the source path. Only matching subdirectories are synced. If include is omitted, all subdirectories are synced.

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

Validate manifest before sync

Contributing

See CONTRIBUTING.md for development setup, building, testing, and linting instructions.

Inspiration

Built based on inspiration from these other projects,

• rule-tool

License

See LICENSE for details.