diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1683bbe..6c5bcea 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,6 +2,11 @@ name: CI on: pull_request: + paths: + - .github/workflows/ci.yml + - Cargo.toml + - Cargo.lock + - src/** env: CARGO_TERM_COLOR: always diff --git a/README.md b/README.md index 5b16fec..f62f062 100644 --- a/README.md +++ b/README.md @@ -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. @@ -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 @@ -51,34 +50,26 @@ 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 ` 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 `. ``` agentfiles init [PATH] [OPTIONS] @@ -86,11 +77,9 @@ agentfiles init [PATH] [OPTIONS] | Option | Description | Default | |---|---|---| -| `PATH` | Directory to initialize | `.` (current directory) | +| `PATH` | Directory to create the manifest in | `.` (current directory) | | `-n, --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 @@ -101,7 +90,7 @@ 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] @@ -109,16 +98,19 @@ 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 ` | Installation scope: `project` or `global` | `project` | | `-p, --providers ` | Target providers (comma-separated) | All providers | -| `--strategy ` | File placement: `copy` or `link` (symlink) | Per-file manifest setting | +| `--strategy ` | File placement: `copy` or `link` (symlink) | Per-dependency manifest setting | +| `--pick ` | 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 ` | 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 @@ -126,17 +118,14 @@ 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 @@ -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` @@ -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 [OPTIONS] +``` + +| Option | Description | Default | +|---|---|---| +| `SOURCE` | Source to remove (matches by normalized URL) | | +| `--clean` | Also delete installed files from provider directories | | +| `-s, --scope ` | Installation scope used when installing (for `--clean`) | `project` | +| `-p, --providers ` | Target providers to clean (for `--clean`) | All providers | +| `--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. @@ -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" } + ] } ] } @@ -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 @@ -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