Skip to content

docs(readme): revise readme with expanded cli and manifest docs #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
leodiegues merged 2 commits into from
Feb 16, 2026
Merged

docs(readme): revise readme with expanded cli and manifest docs #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4a18ee7
docs(readme): revise readme with expanded cli and manifest docs
leodiegues Feb 16, 2026
06b9922
ci(github): limit pr workflow runs to relevant files
leodiegues Feb 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@ name: CI

on:
pull_request:
paths:
- .github/workflows/ci.yml
- Cargo.toml
- Cargo.lock
- src/**

env:
CARGO_TERM_COLOR: always
Expand Down
182 changes: 120 additions & 62 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
# agentfiles

> **Warning:** This project is in early development (v0.0.1) and is **not production-ready**.
> APIs, CLI flags, manifest format, and behavior may change without notice between versions.
> Use at your own risk.
> [!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.

Expand All @@ -27,10 +26,10 @@ Run `agentfiles matrix` to see this table at any time.
curl -fsSL https://raw.githubusercontent.com/leodiegues/agentfiles/main/install.sh | sh
```

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

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

### Cargo
Expand All @@ -51,46 +50,36 @@ cargo build --release
## Quick Start

```sh
# 1. Create a directory with some agent files
mkdir -p my-agents/skills/code-review
cat > my-agents/skills/code-review/SKILL.md << 'EOF'
# Code Review
Review code changes for bugs, style issues, and improvements.
EOF

mkdir -p my-agents/commands
cat > my-agents/commands/deploy.md << 'EOF'
# Deploy
Run the deployment pipeline for the current project.
EOF

# 2. Initialize a manifest
cd my-agents
# 1. Initialize a manifest in your project
agentfiles init

# 3. Install into the current project for all providers
# 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
```

This creates an `agentfiles.json` manifest from the discovered files and installs them into each provider's expected directory structure.
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

### `agentfiles init`

Initialize a new `agentfiles.json` manifest by auto-discovering agent files in the target directory.
Create a new `agentfiles.json` manifest. The manifest starts empty -- add dependencies with `agentfiles install <source>`.

```
agentfiles init [PATH] [OPTIONS]
```

| Option | Description | Default |
|---|---|---|
| `PATH` | Directory to initialize | `.` (current directory) |
| `PATH` | Directory to create the manifest in | `.` (current directory) |
| `-n, --name <NAME>` | Package name | Inferred from directory name |

The command scans for `skills/`, `commands/`, and `agents/` directories and generates a manifest with all discovered files.

```sh
# Initialize in the current directory
agentfiles init
Expand All @@ -101,42 +90,42 @@ agentfiles init ./my-agents --name "my-custom-agents"

### `agentfiles install`

Install agent files from a manifest or remote git repository into provider directories.
Install agent files from dependencies in `agentfiles.json`, or add a new source.

```
agentfiles install [SOURCE] [OPTIONS]
```

| Option | Description | Default |
|---|---|---|
| `SOURCE` | Local path, directory, or git URL | `.` (current directory) |
| `SOURCE` | Local path or git URL. If omitted, installs all deps from `agentfiles.json` | |
| `-s, --scope <SCOPE>` | Installation scope: `project` or `global` | `project` |
| `-p, --providers <PROVIDERS>` | Target providers (comma-separated) | All providers |
| `--strategy <STRATEGY>` | File placement: `copy` or `link` (symlink) | Per-file manifest setting |
| `--strategy <STRATEGY>` | File placement: `copy` or `link` (symlink) | Per-dependency manifest setting |
| `--pick <ITEMS>` | Cherry-pick specific items by name (comma-separated) | |
| `--no-save` | Do not save the source to `agentfiles.json` after installing | |
| `--dry-run` | Preview what would be installed without making changes | |
| `--root <ROOT>` | Project root directory | `.` |

**Install from local directory:**
**Install all dependencies from the manifest:**

```sh
# Install all files from the current directory to all providers
# 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

# Use symlinks instead of copies
agentfiles install --strategy link

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

**Install from a remote git repository:**
**Add and install from a new source:**

```sh
# 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

Expand All @@ -145,8 +134,25 @@ 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`
Expand All @@ -169,6 +175,46 @@ agentfiles scan
agentfiles scan github.com/org/repo@main
```

### `agentfiles list`

List dependencies from `agentfiles.json`.

```
agentfiles list [ROOT]
```

| Option | Description | Default |
|---|---|---|
| `ROOT` | Project root directory | `.` (current directory) |

```sh
agentfiles list
```

### `agentfiles remove`

Remove a dependency from `agentfiles.json`.

```
agentfiles remove <SOURCE> [OPTIONS]
```

| Option | Description | Default |
|---|---|---|
| `SOURCE` | Source to remove (matches by normalized URL) | |
| `--clean` | Also delete installed files from provider directories | |
| `-s, --scope <SCOPE>` | Installation scope used when installing (for `--clean`) | `project` |
| `-p, --providers <PROVIDERS>` | Target providers to clean (for `--clean`) | All providers |
| `--root <ROOT>` | Project root directory | `.` |

```sh
# 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.
Expand All @@ -179,28 +225,26 @@ agentfiles matrix

## Manifest Format

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

```json
{
"name": "my-agents",
"version": "0.1.0",
"description": "A collection of useful agent skills and commands",
"name": "my-project",
"version": "0.0.1",
"description": "My project agent files",
"author": "Your Name",
"repository": "https://github.com/org/repo",
"files": [
"repository": "https://github.com/org/my-project",
"dependencies": [
"github.com/org/shared-agents",
{
"path": "skills/code-review/SKILL.md",
"kind": "Skill"
},
{
"path": "commands/deploy.md",
"kind": "Command"
},
{
"path": "agents/security.md",
"kind": "Agent",
"strategy": "link"
"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" }
]
}
]
}
Expand All @@ -211,19 +255,33 @@ The `agentfiles.json` manifest describes a collection of agent files:
| Field | Required | Description |
|---|---|---|
| `name` | Yes | Package name |
| `version` | Yes | Package version |
| `version` | No | Package version (defaults to `"0.0.1"`) |
| `description` | No | Short description |
| `author` | No | Author name |
| `repository` | No | Source repository URL |
| `files` | Yes | Array of file mappings |
| `dependencies` | No | Array of dependency sources (omitted when empty) |

### Dependency formats

### File mapping fields
Dependencies can be a simple string or a detailed object:

**Simple form** -- just a URL or local path:

```json
"github.com/org/repo"
```

**Detailed form** -- with options:

| Field | Required | Description |
|---|---|---|
| `path` | Yes | Relative path to the file from the manifest directory |
| `kind` | Yes | File type: `Skill`, `Command`, or `Agent` |
| `strategy` | No | Placement strategy: `copy` (default) or `link` (symlink) |
| `source` | Yes | URL or local path |
| `ref` | No | Git ref (branch, tag, or commit) to check out |
| `pick` | No | Cherry-pick specific items by name |
| `strategy` | No | Override placement strategy: `Copy` (default) or `Link` (symlink) |
| `paths` | No | Custom directory-to-kind mappings (replaces default convention) |

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

## Remote Git Sources

Expand Down Expand Up @@ -264,7 +322,7 @@ agents/
- **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 both `agentfiles init` (for auto-discovery) and `agentfiles scan`.
This structure is used by `agentfiles scan` for discovery and `agentfiles install` for scanning sources.

## Contributing

Expand Down