Typical Workflows
This page walks through the workflows you’ll use most often with Ion, from setting up a new project to collaborating with a team.
Each section has two tabs — Terminal commands for running Ion yourself, and Agent prompt to paste directly into Claude Code, Cursor, or any agent.
New project setup
You have a codebase and want to make it agent-ready.
$ ion init
? Select agent targets: [claude] cursor windsurf
? Set up AGENTS.md? [Y/n] (template: rust)
✓ Created Ion.toml with 1 target: claude → .claude/skills
✓ Created AGENTS.md from template
✓ Updated Ion.toml with template sourceion init detects your project language (Cargo.toml → rust, pyproject.toml → python, both → rust+python, Project.toml → julia) and offers to set up an AGENTS.md context file inline — no separate command needed.
Commit the results:
$ git add Ion.toml AGENTS.md .gitignore
$ git commit -m "chore: set up ion"Set up Ion in this project: run `ion init` to create Ion.toml, detect whether I'm using Rust, Python, or Julia and initialize an AGENTS.md with the right builtin template, then commit the result.
Finding and adding a skill
Search across registries and GitHub, then install from the interactive picker:
$ ion search brainstorm
1 brainstorming obra/superpowers ★ 204
Ideates before any creative or feature work
2 feature-brainstorm acme/skills ★ 12
[↑↓ select enter install q quit]Selecting a result installs immediately — no separate ion add step needed.
To add directly without searching:
$ ion add obra/superpowers/brainstorming
✓ Installed brainstorming → .agents/skills/brainstorming/
✓ Updated Ion.toml and Ion.lockUse `ion search` to find skills relevant to this project's main workflow, show me the options, then add the best match with `ion add`.
Cloning a project that already uses Ion
Skills are gitignored and tracked in Ion.toml. After cloning, one command restores everything:
$ git clone git@github.com:acme/my-project && cd my-project
$ ion add
Installing 4 skill(s)...
✓ brainstorming
✓ feature-dev
✓ writing-plans
✓ commit-commands
Done!ion add with no arguments reads Ion.toml and installs all declared skills at the pinned versions from Ion.lock.
This project uses Ion for skill management. Run `ion add` with no arguments to install all skills declared in Ion.toml at the pinned versions from Ion.lock.
Writing a local skill
Local skills live in your project and are tracked by git directly.
$ ion new
Skill name: deploy-staging
✓ Created .agents/skills/deploy-staging/SKILL.md
✓ Registered 'deploy-staging' in Ion.toml as local skillThen edit the generated SKILL.md with your instructions. Validation runs automatically after creation — warnings surface immediately. Run it again any time:
$ ion validate .agents/skills/deploy-staging/
✓ deploy-staging no issuesCreate a new local skill for this project's main recurring workflow: use `ion new` to scaffold it, then write a SKILL.md with clear instructions for when to use it and what steps to follow. Run `ion validate` on the result.
Customizing a remote skill
Eject a remote skill into an editable local copy:
$ ion list
brainstorming obra/superpowers v1.2.0 ✓
feature-dev obra/superpowers v1.2.0 ✓
$ ion skill eject brainstorming
✓ Copied to .agents/skills/brainstorming/
✓ Converted to local in Ion.toml (forked-from: obra/superpowers)
✓ Removed from .gitignoreThe skill is now tracked in git and fully yours to edit. The forked-from metadata records where it came from.
Eject the skill I want to customize: run `ion list` to see what's installed, then `ion skill eject <name>` to copy it locally. The skill will be tracked in git with a forked-from reference.
Keeping skills up to date
$ ion update
✓ brainstorming abc1234 → def5678
✓ feature-dev up to date
✓ writing-plans abc1234 → 9f02b1a
— deploy-staging local, skipped
Summary: 2 updated, 1 up to date, 1 skippedLocal and pinned skills are skipped automatically. To update a single skill:
$ ion update brainstormingCheck for outdated skills with `ion update` and apply any available updates. Local and pinned skills will be skipped automatically. Show me a summary of what changed.
Merging upstream AGENTS.md changes
When your template source publishes updates, ion update flags it and stages the new content:
$ ion update
✓ brainstorming updated
! agents template: a3f91c → 7b20de
upstream saved to .agents/templates/AGENTS.md.upstreamReview the diff and merge with your agent:
$ ion agents diff
--- local/AGENTS.md
+++ upstream/AGENTS.md
@@ -12,3 +12,8 @@
## Testing
+### Property-based tests
+Use proptest for ...Ask your agent: “Merge the upstream AGENTS.md changes into my local version.”
Run `ion update` to check for AGENTS.md template updates. If there's a new upstream version, run `ion agents diff` to see what changed, then help me merge the upstream changes into my local AGENTS.md.
Building a binary skill
Binary skills are compiled CLI tools invoked via ion run. Scaffold a new one:
$ ion init --bin my-linter
✓ Cargo project scaffolded
✓ SKILL.md created
Set up GitHub Actions CI/CD? [Y/n]
✓ .github/workflows/ci.yml
✓ .github/workflows/release.yml
✓ .github/workflows/release-plz.ymlTest it locally while developing:
$ cd my-project
$ ion add --dev ../my-linter
✓ Registered 'my-linter' (dev mode) — ion run forwards to cargo run
$ ion run my-linter check --fixOnce ready to publish, push to GitHub. The release workflow builds binaries for macOS and Linux automatically. Users install with:
$ ion add your-org/my-linterScaffold a new binary skill project with `ion init --bin <name>`. Set up GitHub Actions CI/CD when prompted, then help me implement the core logic and write the SKILL.md so agents know when and how to invoke it.
Quick reference
ion init # set up project (targets + AGENTS.md)
ion add <src> # install a remote skill
ion add # restore all skills (after git clone)
ion new # create a local skill
ion update # pull latest versions
ion list # what's installed
ion search <q> # find skills
ion remove <n> # uninstall a skill