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 checks for Rust (Cargo.toml) and Python (pyproject.toml, setup.py, or requirements.txt) first, detecting rust+python when Rust and any Python marker are both present. It then checks, in order, for Julia (Project.toml), Astro (astro.config.mjs, .js, .ts, or .cjs), and TypeScript (tsconfig.json, or package.json together with src/index.ts or index.ts). Ion 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, Julia, TypeScript, or Astro, 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