agentfiles

[!WARNING] This project is in early development and is not production-ready. APIs, CLI flags, manifest format, and behavior may change without notice between versions. Use at your own risk.

A CLI that installs agent files (skills, commands, agents) across multiple agentic coding providers from a unified agentfiles.json manifest.

Write your agent files once, install them everywhere -- Claude Code, OpenCode, Codex, and Cursor.

Supported Providers

Run agentfiles matrix to see this table at any time.

Installation

Shell script (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/leodiegues/agentfiles/main/install.sh | sh

You can pin a version with VERSION=vX.Y.Z and change the install location with INSTALL_DIR:

VERSION=vX.Y.Z INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/leodiegues/agentfiles/main/install.sh | sh

Cargo

cargo install agentfiles

Build from source

git clone https://github.com/leodiegues/agentfiles.git
cd agentfiles
cargo build --release
# Binary is at target/release/agentfiles

Quick Start

# 1. Initialize a manifest in your project
agentfiles init

# 2. Install agent files from a remote repository
agentfiles install github.com/org/shared-agents

# 3. Or install from a local directory
agentfiles install ../my-agents

# 4. Re-install all saved dependencies
agentfiles install

The first install <source> scans the source for agent files, installs them into each provider's expected directory structure, and saves the source as a dependency in agentfiles.json. Running agentfiles install with no arguments re-installs all saved dependencies.

Commands

Global Options

These options can be used with any command:

agentfiles init

Create a new agentfiles.json manifest. The manifest starts empty -- add dependencies with agentfiles install <source>.

agentfiles init [PATH] [OPTIONS]

# Initialize in the current directory
agentfiles init

# Initialize in a specific directory with a custom name
agentfiles init ./my-agents --name "my-custom-agents"

agentfiles install

Install agent files from dependencies in agentfiles.json, or add a new source.

agentfiles install [SOURCE] [OPTIONS]

Install all dependencies from the manifest:

# Install everything listed in agentfiles.json
agentfiles install

# Install to specific providers only
agentfiles install -p claude-code,cursor

# Install globally (user-wide, not project-scoped)
agentfiles install -s global

Add and install from a new source:

# Install from a local directory (auto-saves to agentfiles.json)
agentfiles install ./my-agents

# Install from a GitHub repository
agentfiles install github.com/org/repo

# Install from a specific branch or tag
agentfiles install github.com/org/repo@v1.0

# Install from a full URL
agentfiles install https://github.com/org/repo.git@main

# Use symlinks instead of copies
agentfiles install github.com/org/repo --strategy link

# Cherry-pick specific items
agentfiles install github.com/org/repo --pick skills/review,commands/deploy

# Install without saving to agentfiles.json
agentfiles install github.com/org/repo --no-save

# Preview what would be installed
agentfiles install github.com/org/repo --dry-run

# Install from a specific directory into a specific project root
agentfiles install ./my-agents --root ./my-project

The --pick flag supports kind-prefixed names (skills/review, commands/deploy) or plain names (review) that match any kind.

Provider names for -p are: claude-code, opencode, codex, cursor.

agentfiles scan

Scan a local directory or remote git repository for agent files without installing them. Useful for previewing what would be discovered.

agentfiles scan [SOURCE]

# Scan the current directory
agentfiles scan

# Scan a remote repository
agentfiles scan github.com/org/repo@main

# Scan with verbose output for troubleshooting
agentfiles --verbose scan github.com/org/repo

agentfiles list

List dependencies from agentfiles.json.

agentfiles list [ROOT]

agentfiles list

agentfiles remove

Remove a dependency from agentfiles.json.

agentfiles remove <SOURCE> [OPTIONS]

# Remove a dependency
agentfiles remove github.com/org/repo

# Remove and clean up installed files
agentfiles remove github.com/org/repo --clean

agentfiles matrix

Display the provider compatibility matrix showing which file kinds each provider supports.

agentfiles matrix

Manifest Format

The agentfiles.json manifest lists dependencies (remote or local sources) that provide agent files. It lives in your project root, similar to package.json.

{
  "name": "my-project",
  "version": "0.0.1",
  "description": "My project agent files",
  "author": "Your Name",
  "repository": "https://github.com/org/my-project",
  "dependencies": [
    "github.com/org/shared-agents",
    {
      "source": "github.com/org/more-agents",
      "ref": "v2.0",
      "pick": ["skills/review", "commands/deploy"],
      "strategy": "Link",
      "paths": [
        { "path": "prompts", "kind": "skill" },
        { "path": "macros", "kind": "command" }
      ]
    }
  ]
}

Fields

Dependency formats

Dependencies can be a simple string or a detailed object:

Simple form -- just a URL or local path:

"github.com/org/repo"

Detailed form -- with options:

Each entry in paths has a path (relative to source) and a kind (skill, command, or agent).

Remote Git Sources

agentfiles can install directly from git repositories. Supported URL formats:

Recognized shorthand hosts: github.com, gitlab.com, bitbucket.org, codeberg.org, sr.ht.

Remote repositories are cached locally. Subsequent installs from the same URL will fetch updates instead of re-cloning.

The remote repository should either contain an agentfiles.json manifest or use the standard directory structure so that files can be auto-discovered.

File Conventions

agentfiles expects agent files to follow a specific directory structure:

skills/
  code-review/
    SKILL.md          # Each skill is a directory with a SKILL.md file
  refactor/
    SKILL.md
commands/
  deploy.md           # Each command is a .md file
  test.md
agents/
  security.md         # Each agent is a .md file
  performance.md

• Skills -- A directory containing a SKILL.md file (e.g., skills/code-review/SKILL.md).
• Commands -- A .md file in the commands/ directory (e.g., commands/deploy.md).
• Agents -- A .md file in the agents/ directory (e.g., agents/security.md).

This structure is used by agentfiles scan for discovery and agentfiles install for scanning sources.

Contributing

See CONTRIBUTING.md for development setup, code style, testing conventions, and how to submit changes.

License

MIT