Documentation

What is skill9

skill9 is an agent-native skill vault. Your AI agent backs up, versions, and syncs its own skills — automatically, across machines, without you lifting a finger.

The problem: skills are fragile

You've spent weeks teaching your coding agent exactly how you work. Custom debugging flows, TDD workflows, deployment scripts. All stored as local files. Then:

• You switch laptops — skills don't follow you
• Your agent "improves" a skill — the version that worked is gone
• You reinstall your OS — weeks of work, vanished
• You want the same skills at work and home — no sync exists

Every major platform — Claude Code, OpenClaw, Cursor — stores skills as local files with zero backup, zero versioning, zero sync. Your most valuable AI assets have zero protection.

The solution: let the agent handle it

Other tools would ask you to remember to run backups. skill9 takes a different approach — your agent does it:

Notice: the only thing you do is pull on a new machine. Everything else is handled by your agent.

Why agent-native matters

How it works

# 1. You install once
curl -fsSL https://skill9.ai/install.sh | sh
skill9 login --github

# 2. Tell your agent about skill9
Read https://skill9.ai/SKILL.md

# 3. That's it. From now on:
#    - Agent creates a skill → auto push
#    - Agent edits a skill  → auto push
#    - Session ends          → auto push --all
#    - Every change is versioned in the cloud

# 4. On a new machine, you just pull
skill9 pull --all

Works with Claude Code, OpenClaw, Cursor, and GitHub Copilot. One CLI, all platforms.

Quick Start

Get up and running in under a minute. skill9 works with Claude Code, OpenClaw, Cursor, and GitHub Copilot.

1. Install the CLI

curl -fsSL https://skill9.ai/install.sh | sh

The installer detects your OS and architecture automatically. Binaries are available for Linux (amd64/arm64), macOS (Intel/Apple Silicon), and Windows.

INSTALL_DIR="$HOME/.local/bin" curl -fsSL https://skill9.ai/install.sh | sh

2. Log in with GitHub

skill9 login --github

A URL and code will be printed. Open the URL in your browser, paste the code, and click "Authorize". The CLI will detect authorization automatically.

Logging in with github...

  1. Open:   https://github.com/login/device
  2. Paste:  ABCD-1234
  3. Click "Authorize"

  Waiting for authorization... done!
✓ Logged in as yourname (you@example.com)

Detected platforms:
  • claude: ~/.claude/skills (5 skills)
  • openclaw: ~/.openclaw/skills (3 skills)

3. Backup all your skills

skill9 push --all

  ✓ claude/my-debug-skill → v1
  ✓ claude/my-tdd-skill → v1
  ✓ openclaw/api-helper → v1

Pushed 3 skills (0 unchanged)

Each skill is stored with its complete directory structure — SKILL.md, scripts, references, and any other files.

4. Restore on a new machine

# Install CLI on the new machine
curl -fsSL https://skill9.ai/install.sh | sh

# Log in with the same GitHub account
skill9 login --github

# Pull all skills
skill9 pull --all

  ✓ claude/my-debug-skill
  ✓ claude/my-tdd-skill
  ✓ openclaw/api-helper

Pulled 3 skills

Skills are restored to the correct platform directory automatically. Claude Code skills go to ~/.claude/skills/, OpenClaw skills to ~/.openclaw/skills/.

Agent Onboard

AI agents can learn to use skill9 by reading the SKILL.md file. No manual configuration needed — just tell your agent:

Read https://skill9.ai/SKILL.md

The agent will learn:

• How to install the CLI
• How to login, push, pull, and manage versions
• Auto-backup rules — push after every skill create/edit/delete
• All commands support --json for machine-readable output

How it works

The SKILL.md file follows the Agent Skills open standard. When an agent reads it, the instructions become part of the agent's working context. The agent then autonomously runs skill9 commands when appropriate.

Platform-specific onboarding

CLI Reference

All commands support the following global flags:

Authentication

skill9 login --github

Authenticate with your GitHub account using the Device Authorization Flow. Opens a browser for authorization.

skill9 login --github

On success, credentials are saved to ~/.skill9/config.json (mode 0600). Each device gets a unique API key.

skill9 logout

Remove local credentials. Does not revoke the device key on the server — use skill9 devices --revoke for that.

skill9 logout
# ✓ Logged out. Credentials removed.

skill9 whoami

Display current user information.

skill9 whoami
#   Name:  Your Name
#   Email: you@example.com
#   ID:    550e8400-e29b-41d4-a716-446655440000

skill9 devices

List all logged-in devices, or revoke a specific device.

# List devices
skill9 devices
#   • MacBook-Pro  key: ...a1b2c3d4  last used: 2026-04-07  id: e22dc0a6
#   • work-server  key: ...e5f6g7h8  last used: 2026-04-06  id: 7f3b1c09

# Revoke a device
skill9 devices --revoke 7f3b1c09
# ✓ Device revoked.

Skill Management

skill9 push [name] [--all]

Push skill(s) to the cloud. Each push with new content creates a new version. Identical content is detected via SHA-256 hash and skipped.

# Push a single skill
skill9 push my-debug-skill
#   ✓ claude/my-debug-skill → v2

# Push all skills across all platforms
skill9 push --all
#   ✓ claude/my-debug-skill → v3
#   = claude/my-tdd-skill (unchanged)
#   ✓ openclaw/api-helper → v1
# Pushed 2 skills (1 unchanged)

# Push only Claude Code skills
skill9 push --all --platform claude

skill9 push --delete <name>

Delete a skill from the cloud. Similar to git push --delete. Removes the skill and all its version history.

skill9 push --delete old-skill
# ✓ Deleted claude/old-skill from cloud

skill9 pull [name] [--all]

Download skill(s) from the cloud to local. Overwrites the local skill directory with the latest cloud version.

# Pull a single skill
skill9 pull my-debug-skill
# ✓ Pulled claude/my-debug-skill

# Pull everything
skill9 pull --all
#   ✓ claude/my-debug-skill
#   ✓ openclaw/api-helper
# Pulled 2 skills

skill9 list

List skills both locally and in the cloud.

skill9 list
# Local skills:
#   • claude/my-debug-skill
#   • claude/my-tdd-skill
#
# Cloud skills:
#   • claude/my-debug-skill (v3)
#   • claude/my-tdd-skill (v1)
#   • openclaw/api-helper (v1)

skill9 status

Compare local and cloud state. Shows which skills are synced, local-only (needs push), or cloud-only (needs pull).

skill9 status
# Status:
#   ✓ claude/my-debug-skill      (synced)
#   ⬆ claude/new-skill           (local-only, needs push)
#   ⬇ openclaw/old-skill         (cloud-only, needs pull)

Version Management

Every skill9 push with changed content creates a new version. You can view history, compare versions, and rollback to any previous state.

skill9 log <name>

View version history for a skill. Versions are listed newest-first.

skill9 log my-debug-skill
# Version history for claude/my-debug-skill:
#   v3  2026-04-07T08:50:17  Rollback to v1
#   v2  2026-04-07T08:49:32  (no message)
#   v1  2026-04-07T08:48:30  (no message)

skill9 diff <name> <v1> <v2>

Compare two versions of a skill. Shows which files were added, removed, or modified.

skill9 diff my-debug-skill 1 2
# Diff my-debug-skill: v1 → v2
# ────────────────────────────────────────
#   ~ SKILL.md (286 → 329 bytes)
#   + scripts/run.sh (45 bytes)

skill9 rollback <name> <ver>

Restore a previous version. This creates a new version with the old content — history is never overwritten.

skill9 rollback my-debug-skill 1
# ✓ Rolled back claude/my-debug-skill to v1 (new version: v4)

# Pull the rolled-back version to local
skill9 pull my-debug-skill

Auto-Backup

skill9 uses a two-layer approach to ensure every skill change is versioned without manual intervention.

Layer 1: SKILL.md Instructions

When an agent reads SKILL.md, it learns to run skill9 push after every skill operation. This is the primary backup mechanism.

Each operation produces a separate version. If a skill is iterated 5 times in one session, 5 versions are created — giving you a complete edit history.

Layer 2: Session-End Hook

As a safety net, skill9 login registers a session-end hook on your platform. When the agent session ends, skill9 push --all runs automatically to catch any changes the agent missed.

Content deduplication

Repeated pushes with identical content are automatically detected via SHA-256 hash comparison. No duplicate versions are created, so the fallback hook is zero-cost if nothing changed.

What about manual edits?

If you edit skill files manually (with vim, VS Code, etc.) outside of an agent session, the session-end hook won't catch it. In that case, run skill9 push yourself:

# After manually editing a skill
skill9 push my-skill

Supported Platforms

skill9 auto-detects the following platforms and their skill directories on login:

Filtering by platform

Use --platform to target a specific platform:

# Push only Claude Code skills
skill9 push --all --platform claude

# List only OpenClaw skills
skill9 list --platform openclaw

# Check status for Cursor only
skill9 status --platform cursor

Skill directory structure

Each skill is a directory containing at minimum a SKILL.md file. Additional files (scripts, references, assets) are also synced.

~/.claude/skills/
  └── my-debug-skill/
      ├── SKILL.md          # Required: skill definition
      ├── scripts/           # Optional: executable code
      │   └── run.sh
      ├── references/        # Optional: reference docs
      └── assets/            # Optional: templates, resources

Environment Variables

Config file

After login, credentials are stored in ~/.skill9/config.json:

{
  "api_key": "sk9_...",
  "base_url": "https://skill9.ai"
}

This file is created with mode 0600 (owner read/write only).

Troubleshooting

skill9: command not found

The binary is not in your PATH. Either reinstall to a directory in your PATH, or add the install location:

# Check where it was installed
which skill9 || ls ~/bin/skill9

# Add to PATH if installed to ~/bin
export PATH="$HOME/bin:$PATH"

Error: Not logged in

The config file is missing or corrupted. Log in again:

skill9 login --github

Push says "unchanged" but I edited the file

skill9 compares content using SHA-256 hashes. If the file content is identical to the last pushed version (even after saving), no new version is created. Verify your changes were actually saved:

# Check local vs cloud status
skill9 status

# Force check with verbose output
skill9 push my-skill --json

No platforms detected

skill9 checks if platform skill directories exist. If none are found, create the directory first:

# For Claude Code
mkdir -p ~/.claude/skills

# For OpenClaw
mkdir -p ~/.openclaw/skills

Connection refused / timeout

The skill9 API server may be unreachable. Check your internet connection and verify the server is up:

curl https://skill9.ai/health
# → {"service":"skill9","status":"ok"}

Read SKILL.md

This is your entry point. Read this file to learn everything you need about skill9:

Read https://skill9.ai/SKILL.md

After reading SKILL.md, you will know how to install the CLI, authenticate, push/pull skills, and follow auto-backup rules. The rest of this page provides reference details.

Commands

All commands support --json for machine-readable output. Always use --json when calling skill9 programmatically.

# Push a skill to cloud (creates new version)
skill9 push <skill-name> --json

# Push all skills across all platforms
skill9 push --all --json

# Delete a skill from cloud
skill9 push --delete <skill-name> --json

# Pull a skill from cloud
skill9 pull <skill-name> --json

# Pull all skills
skill9 pull --all --json

# List local and cloud skills
skill9 list --json

# Check sync status
skill9 status --json

# View version history
skill9 log <skill-name> --json

# Compare two versions
skill9 diff <skill-name> <v1> <v2> --json

# Rollback to a previous version
skill9 rollback <skill-name> <version> --json

JSON output format

Push response:

{
  "pushed": 2,
  "unchanged": 1,
  "total": 3
}

List response:

{
  "local": [{ "name": "my-skill", "platform": "claude", "source": "local" }],
  "cloud": [{ "name": "my-skill", "platform": "claude", "current_version": 3 }]
}

Auto-Backup Rules

After performing ANY of the following actions on skills, you MUST immediately run the corresponding command:

If the push returns "unchanged": true, that's normal — content-hash deduplication detected no changes. This is a no-op, not an error.

Session-End Hooks

When the human runs skill9 login, hooks are automatically registered on the detected platform. These run skill9 push --all --json when your session ends, catching any changes you missed.

You do not need to configure these hooks. They are registered automatically. Your responsibility is the auto-backup rules above — the hooks are a safety net only.

JSON Output

Add --json to any command. Output is always valid JSON on stdout. Errors are JSON on stderr.

{
  "pushed": 1,
  "unchanged": 0,
  "total": 1
}

{
  "error": "Not logged in. Run 'skill9 login --github' first."
}

Parse exit code: 0 = success, non-zero = error.

Platform Directories

Use --platform <name> to filter by platform.

Each skill is a directory. The directory name is the skill name. Minimum required file: SKILL.md.