Quick Start

This guide walks through the basics of using Ion to manage skills in a project.

Initialize a project

Start by creating an Ion.toml manifest in your project:

ion init

This prompts you to select which AI agent targets to configure (Claude, Cursor, Windsurf, etc.) and — if Ion detects your project language — offers to set up an AGENTS.md context file inline.

Add a skill

Add a skill from GitHub:

ion add owner/repo/skill-name

Ion will:

1. Resolve the source and fetch the skill
2. Validate its structure and security
3. Install it to the configured target directory
4. Update Ion.toml and Ion.lock

Install all skills

If you already have an Ion.toml with skills listed, install everything:

ion add

This reads the manifest and installs all declared skills, using the lockfile for exact versions. Run this after cloning a project.

Create a local skill

Create a skill that lives in your project:

ion new

Ion prompts for a name and creates a SKILL.md in your skills directory (.agents/skills/<name>/ by default) with the proper frontmatter template. Validation runs automatically after creation.

To create at a specific path without a name prompt:

ion new --path .agents/skills/my-skill

Check skill quality

Validate a skill against Ion’s built-in checks:

ion validate path/to/skill

The validator checks for security issues, structural problems, and adherence to the skill format.

Search for skills

Find skills across configured sources:

ion search "code review"

An interactive TUI picker lets you browse results and install directly.