# Skilo

> Share agent skills with a link. Add, sync, and pack them across Claude Code, Codex, Cursor, Amp, Windsurf, OpenCode, Cline, Roo, and OpenClaw.

Skilo is a transfer-first CLI and handoff layer for agent skills. Skills are directories containing a `SKILL.md` file with markdown instructions and optional YAML frontmatter. The main job is simple: share a skill, install it somewhere else, sync between tools, or make a pack. Public discovery exists, but it is secondary.

## Quick start

```
$ npx skilo-cli share ./code-reviewer
→ skilo.xyz/s/a3xK9mP2
$ skilo add skilo.xyz/s/a3xK9mP2
✓ Installed code-reviewer
$ skilo pack ./code-reviewer flrabbit/original-landing-page-builder --name "Starter pack"
→ skilo.xyz/p/abc123
```

No account required. Skills are published anonymously by default. You can claim them later with `skilo claim`, or create a namespace up front with `skilo login yaz`.

For humans, every `npx skilo-cli ...` run refreshes the global `skilo` binary in the background, and the installed `skilo` command keeps itself updated too.
For agents, prefer `npx skilo-cli --json` and parse the structured output.

Skilo is transfer-first. The main flows are `share`, `add`, `sync`, and `pack`. Public search exists, but it is secondary.

## CLI commands

### `skilo share <path>`

Create a shareable link for a local skill directory. Publishes the skill and returns a URL.

- `--one-time` — link expires after first use
- `--expires 2h` — auto-expire after a duration (m, h, d)
- `--uses 5` — limit total downloads
- `--password` — require a password to access
- `--listed` — make the underlying skill public before linking

`skilo share` is transfer-first. Local shares default to unlisted even when you are logged in.

### `skilo share <tool>`

Share all skills from an AI tool at once. Supported tools: `claude`, `codex`, `cursor`, `opencode`, `amp`, `windsurf`, `cline`, `roo`, or `all`.

- `-y` — skip interactive selection, share everything

Creates a pack link containing all shared skills when 2+ are selected.

### `skilo add <skill>`

Install a skill or pack. Accepts a share URL, pack URL, namespace/name, .skl file, GitHub URL, or local path.

- If exactly one supported tool is detected, Skilo installs there automatically.
- If multiple tools are detected, interactive runs prompt once.
- Non-interactive runs should pass explicit flags or set `SKILO_TARGETS`.
- If nothing is detected, Skilo falls back to Claude Code.

Install targets (flags):

- `--cc` / `--claude-code` → `~/.claude/skills/`
- `--codex` → `~/.agents/skills/`, `~/.codex/skills/`
- `--cursor` → `~/.cursor/skills/`
- `--amp` → `~/.config/agents/skills/`
- `--windsurf` → `~/.codeium/windsurf/skills/`
- `--oc` / `--opencode` → `~/.config/opencode/skills/`
- `--cline` → `~/.cline/skills/`
- `--roo` → `~/.roo/skills/`
- `--openclaw` → `~/.openclaw/skills/`

### `skilo sync <from> <to>`

Copy skills from one tool into another tool without going through a repo.

- `skilo sync claude opencode`
- `skilo sync claude codex --all`
- `skilo sync codex cursor --skill reviewer`

### `skilo pack [sources...]`

Turn multiple skills, links, refs, or repo sources into one pack link.

- `skilo pack ./reviewer ./planner --name "Daily kit"`
- `skilo pack skilo.xyz/s/abc123 vercel-labs/skills@find-skills`
- `skilo add skilo.xyz/p/abc123` to install the resulting pack

### `skilo publish`

Publish the current directory to the registry. Reads SKILL.md for metadata.

- `--listed` — publish publicly under your namespace
- `--unlisted` — publish direct-link only

### `skilo login <username>`

Create a publishing identity with a username and save an API key locally.

- `skilo login yaz`
- `skilo login --token sk_...`

### `skilo list --published`

List skills under your logged-in namespace, including public vs unlisted visibility.

### `skilo search <query>`

Search public skills by name or description. Use this when you want discovery, not for the main transfer loop.

### `skilo inspect <skill>`

View a skill's SKILL.md, checksum, and metadata without installing.

### `skilo export` / `skilo import <source>`

Export to a .skl file for offline sharing, or import from a .skl file, GitHub repo, or local path.

## SKILL.md format

Every skill is a directory with a SKILL.md file. The file uses YAML frontmatter for metadata and markdown for the skill content.

```yaml
---
name: my-skill
description: What this skill does
version: 0.1.0
author: your-name
---

# my-skill

Instructions for the agent...
```

Fields: `name` and `description` are required. `version`, `author`, `homepage`, `repository`, and `keywords` are optional.

## Supported sources

- Local skill path
- Local SKILL.md or skill.md
- Skilo share link: `skilo.xyz/s/<token>`
- Registry ref: `namespace/name` or `namespace/name@version`
- GitHub shorthand: `github:user/repo` or `github:user/repo#path`
- `.skl` bundle
- Direct URL

## Trust and verification

Every published skill has a SHA-256 checksum. The CLI verifies integrity on install.

- **Anonymous** — published without an account. Inspect before installing.
- **Claimed** — a user has claimed ownership with `skilo claim`.
- **Verified** — publisher identity confirmed. Skill is cryptographically signed.

Use `skilo inspect` to review a skill's content and checksum before you install.

## Claim a skill

When you publish a skill anonymously, you get a claim token. Use it to take ownership later — no account needed at publish time.

1. **Publish a skill.** When you run `skilo publish` without being logged in, you get an anonymous namespace and a claim token.
2. **Save the token.** The CLI saves it to `~/.skilo/claims/` automatically. You'll also see it in the terminal output.
3. **Log in and claim.** When you're ready to own the skill under your name, log in and run the claim command.

```
skilo claim @namespace/skill-name --token YOUR_TOKEN
```

Log in with:

```
skilo login your-name
```

## Supported tools

Skilo discovers skills from these directories:

| Tool | Directory |
|---|---|
| Claude Code | `~/.claude/skills/` |
| Codex | `~/.agents/skills/`, `~/.codex/skills/` |
| Cursor | `~/.cursor/skills/` |
| Amp | `~/.config/agents/skills/` |
| Windsurf | `~/.codeium/windsurf/skills/` |
| OpenCode | `~/.config/opencode/skills/` |
| Cline | `~/.cline/skills/` |
| Roo | `~/.roo/skills/` |
| OpenClaw | `~/.openclaw/skills/` |

## API

- Health: `GET https://skilo-api.yaz-b35.workers.dev/health`
- Resolve share: `GET /v1/skills/share/:token` → `{ skill, requiresPassword }`
- Skill metadata: `GET /v1/skills/:namespace/:name` → skill object
- Skill tarball: `GET /v1/skills/:namespace/:name/tarball/:version` → gzipped tar containing SKILL.md
- Resolve pack: `GET /v1/packs/:token` → `{ name, token, skills[] }`
- Create pack: `POST /v1/packs` with `{ name, share_tokens[] }` → `{ token, url, count }`
- CLI login bootstrap: `POST /v1/auth/cli-login` with `{ username, email? }` → `{ user, apiKey }`
- Current user: `GET /v1/user` → authenticated user
- My skills: `GET /v1/user/skills` → skills under the authenticated namespace

## Links

- Product: https://skilo.xyz
- GitHub: https://github.com/yazcaleb/skilo
- npm: https://www.npmjs.com/package/skilo-cli