https://github.com/roger-luo/ion
Ion - a CLI toolbox for agentic developers
https://github.com/roger-luo/ion
agent cli package-manager skills tools
Last synced: about 1 month ago
JSON representation
Ion - a CLI toolbox for agentic developers
- Host: GitHub
- URL: https://github.com/roger-luo/ion
- Owner: Roger-luo
- Created: 2023-01-26T07:06:15.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-05-07T01:09:18.000Z (about 1 month ago)
- Last Synced: 2026-05-07T02:36:54.698Z (about 1 month ago)
- Topics: agent, cli, package-manager, skills, tools
- Language: Rust
- Homepage: http://ion.rogerluo.dev/
- Size: 4.87 MB
- Stars: 74
- Watchers: 1
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Ion
Agent skill manager for AI coding tools (Claude, Cursor, Windsurf, etc.).
Ion manages installation, validation, and organization of **skills** — reusable prompts and instructions that enhance AI agent capabilities.
## Why Ion
The agent skills ecosystem has grown rapidly. Tools like Vercel's [`npx skills`](https://github.com/vercel-labs/skills) pioneered the idea of an "npm for agent skills." Ion takes a different approach — it's a standalone binary with no runtime dependency, built for reproducible installs and agent-driven workflows.
| | Ion | `npx skills` |
|---|---|---|
| **Runtime** | Single binary (Rust) | Node.js / npx |
| **Manifest & lockfile** | `Ion.toml` + `Ion.lock` with checksums | No lockfile |
| **Reproducibility** | Pinned revisions, lockfile checksums | Latest-only |
| **Validation** | Built-in security, structure, and markdown checks | None |
| **Agent interface** | `--json` mode on every command with structured envelope | None |
| **Local skills** | First-class `type = "local"`, eject from remote | Symlink/copy from path |
| **Binary skills** | Download, checksum, and run compiled tools via `ion run` | Not supported |
| **Self-update** | `ion self update` with signed GitHub Release binaries | npm/npx update |
Ion is designed for teams that want their skill dependencies to be **versioned, validated, and reproducible** — the same properties you expect from a package manager, applied to agent instructions.
## Installation
```bash
curl -fsSL https://raw.githubusercontent.com/Roger-luo/Ion/main/install.sh | sh
```
To install a specific version:
```bash
curl -fsSL https://raw.githubusercontent.com/Roger-luo/Ion/main/install.sh | sh -s -- 0.1.2
```
Or install from source:
```bash
cargo install --git https://github.com/Roger-luo/Ion
```
## Quick Start
```bash
# Initialize a project with a target
ion project init --target claude
# Add a skill
ion add obra/superpowers/brainstorming
# Install all skills from Ion.toml
ion add
# Search for skills
ion search "code review"
# Create a new local skill
ion skill new
# List installed skills
ion skill list
```
## Commands
| Command | Description |
|---------|-------------|
| `ion add [source]` | Add a skill, or install all from Ion.toml |
| `ion remove ` | Remove a skill |
| `ion search ` | Search registries and GitHub |
| `ion update [name]` | Update skills to latest versions |
| `ion run ` | Run a binary skill |
| `ion skill new` | Create a new skill |
| `ion skill eject ` | Eject a remote skill into an editable local copy |
| `ion skill validate` | Validate skill definitions |
| `ion skill list` | List installed skills |
| `ion skill info ` | Show skill details |
| `ion skill link ` | Link a local skill directory |
| `ion project init` | Initialize Ion.toml with targets |
| `ion project migrate` | Migrate from legacy formats |
| `ion cache gc` | Clean up stale cached repos |
| `ion config` | View and set configuration |
## JSON Mode for Agents
All commands support `ion --json ` for structured, non-interactive output. This enables AI agents and CI scripts to operate Ion programmatically.
```bash
# Structured search results
ion --json search "testing"
# Two-stage commands: preview first, then execute
ion --json remove my-skill # returns what would be removed (exit 2)
ion --json remove my-skill --yes # executes the removal (exit 0)
```
See [SKILL.md](SKILL.md) for the full agent interface reference.
## License
MIT