Home › Documentation › CLI Guide

REFERENCE

CLI Guide for OMNISKILL

Complete command-line reference — installation, all 13 commands, configuration, JSON output, and common workflows.

⚡ Installation

From PyPI (Recommended)

$ pip install omniskill

From Source

$ git clone https://github.com/SufficientDaikon/omniskill.git
$ cd omniskill
$ pip install -e .

Verify Installation

$ omniskill --version
omniskill v1.0.0

🚀 Quick Start

Get up and running in 60 seconds:

Initialize
Detect platforms and create your config.
```
$ omniskill init
```
Install Everything
Deploy all skills and bundles to every detected platform.
```
$ omniskill install --all
```
Verify
Run the health check to confirm everything is working.
```
$ omniskill doctor
```

✓

Ready to Go

Your AI coding assistants now have access to all OMNISKILL skills, agents, and pipelines.

🏳️ Global Flags

These flags work with every command:

Flag	Description
`--json`	Output results as structured JSON (see JSON Output)
`--quiet`	Suppress all non-essential output; only show errors
`--verbose`	Show detailed debug-level output
`--version`	Print the OMNISKILL version and exit

$ omniskill doctor --json          # Machine-readable output for CI
$ omniskill install --all --quiet   # Silent operation for scripts
$ omniskill install --skill react-best-practices --verbose  # Debug
$ omniskill --version               # Check installed version

📖 Command Reference

OMNISKILL ships with 13 commands. Each section below shows usage, options, and real-world examples.

`omniskill init`

Initialize OMNISKILL in the current environment. Creates the ~/.omniskill/ config directory, detects installed platforms, and writes a default config.yaml.

Usage

BASH

omniskill init [--platform <name>]

Options

Option	Description
`--platform <name>`	Skip auto-detection and initialize for a specific platform (`claude-code`, `copilot-cli`, `cursor`, `windsurf`, `antigravity`)

Example

$ omniskill init
✓ Detected platforms: claude-code, copilot-cli, cursor
✓ Created ~/.omniskill/config.yaml
✓ OMNISKILL initialized successfully

$ omniskill init --platform cursor
✓ Initialized for platform: cursor
✓ Created ~/.omniskill/config.yaml

`omniskill install`

Install skills, bundles, or everything to one or more platforms.

Usage

BASH

omniskill install [--skill <name>] [--bundle <name>] [--all] [--platform <name>] [--force]

Options

Option	Description
`--skill <name>`	Install a single skill by name
`--bundle <name>`	Install a bundle (domain kit) by name
`--all`	Install all available skills and bundles
`--platform <name>`	Target a specific platform (default: all detected)
`--force`	Overwrite existing installations without prompting

Examples

$ omniskill install --skill react-best-practices
✓ Installed react-best-practices to claude-code
✓ Installed react-best-practices to copilot-cli
✓ Installed react-best-practices to cursor
Installed 1 skill to 3 platforms

$ omniskill install --bundle web-dev-kit
✓ Installing web-dev-kit (5 skills + 1 meta-skill)...
  ✓ frontend-design
  ✓ react-best-practices
  ✓ vercel-react-best-practices
  ✓ web-design-guidelines
  ✓ backend-development
  ✓ web-fullstack-expert (meta-skill)
Installed 6 skills to 3 platforms

$ omniskill install --all
✓ Installing 83 skills, 12 bundles to 3 platforms...
Done in 4.2s

$ omniskill install --skill godot-best-practices --platform cursor --force
✓ Installed godot-best-practices to cursor (overwritten)

`omniskill uninstall`

Remove an installed skill or bundle from one or more platforms.

Usage

BASH

omniskill uninstall <name> [--platform <name>] [--force]

Options

Option	Description
`<name>`	Required. Name of the skill or bundle to remove
`--platform <name>`	Remove from a specific platform only (default: all)
`--force`	Skip confirmation prompt

Example

$ omniskill uninstall godot-best-practices
⚠ This will remove godot-best-practices from 3 platforms. Continue? [y/N] y
✓ Removed godot-best-practices from claude-code
✓ Removed godot-best-practices from copilot-cli
✓ Removed godot-best-practices from cursor
Uninstalled 1 skill from 3 platforms

$ omniskill uninstall web-dev-kit --platform cursor --force
✓ Removed web-dev-kit (6 skills) from cursor

`omniskill doctor`

Run a comprehensive health check. Inspects config files, platform connections, skill integrity, and version status.

Usage

BASH

omniskill doctor [--json]

Options

Option	Description
`--json`	Output results as structured JSON

Example

$ omniskill doctor
OMNISKILL Doctor v1.0.0
──────────────────────────────

Configuration
  ✓ Config file exists          ~/.omniskill/config.yaml
  ✓ Config file valid           YAML syntax OK

Platforms
  ✓ claude-code                 ~/.claude/AGENTS.md found
  ✓ copilot-cli                 ~/.copilot/ found
  ✓ cursor                      ~/.cursor/rules/ found
  ✗ windsurf                    Not detected
  ✗ antigravity                 Not detected

Skills
  ✓ 83 skills installed         0 conflicts detected
  ✓ 12 bundles installed        All meta-skills present
  ✓ All manifests valid         0 schema errors

Version
  ✓ Up to date                  v1.0.0 (latest)

──────────────────────────────
Result: 11 passed, 2 skipped, 0 failed

`omniskill validate`

Validate a skill, bundle, agent, or pipeline against the OMNISKILL schema. Use before committing or opening a PR.

Usage

BASH

omniskill validate [path] [--json]

Options

Option	Description
`[path]`	Path to a skill/bundle/agent/pipeline directory (default: validate all)
`--json`	Output results as structured JSON

Examples

$ omniskill validate skills/my-new-skill
Validating skills/my-new-skill...
  ✓ manifest.yaml              Schema valid
  ✓ SKILL.md                   All required sections present
  ✓ Triggers                   No conflicts with existing skills
  ✓ Resources                  All referenced files exist
Result: PASS (4/4 checks)

$ omniskill validate
Validating 83 skills, 12 bundles, 10 agents, 8 pipelines...
  ✓ 83 skills valid
  ✓ 12 bundles valid
  ✓ 10 agents valid
  ✓ 8 pipelines valid
Result: PASS (113/113 checks)

$ omniskill validate skills/broken-skill --json
{
  "status": "fail",
  "command": "validate",
  "version": "1.0.0",
  "data": {
    "path": "skills/broken-skill",
    "checks": 4,
    "passed": 2,
    "failed": 2,
    "errors": [
      "manifest.yaml: missing required field 'description'",
      "SKILL.md: missing section '## When to Use'"
    ]
  },
  "errors": []
}

`omniskill list`

List installed skills, agents, bundles, or pipelines.

Usage

BASH

omniskill list [skills|agents|bundles|pipelines] [--json]

Options

Option	Description
`skills`	List only skills (default if no sub-command given)
`agents`	List only agents
`bundles`	List only bundles
`pipelines`	List only pipelines
`--json`	Output results as structured JSON

Examples

$ omniskill list skills
OMNISKILL Skills (83 installed)
───────────────────────────────
  backend-development          v1.0.0   [web, api, database]
  capacitor-best-practices     v1.0.0   [mobile, capacitor]
  django-expert                v1.0.0   [python, django]
  frontend-design              v1.0.0   [web, ui, css]
  godot-best-practices         v1.0.0   [gamedev, godot]
  react-best-practices         v1.0.0   [web, react]
  ...

$ omniskill list bundles
OMNISKILL Bundles (12 installed)
───────────────────────────────
  godot-kit                    5 skills    Godot game development
  web-dev-kit                  5 skills    Full-stack web development
  django-kit                   4 skills    Django web framework
  mobile-kit                   3 skills    Mobile app development
  ux-design-kit                6 skills    UX/UI design pipeline
  devops-kit                   3 skills    DevOps and infrastructure
  ...

$ omniskill list agents --json
{
  "status": "ok",
  "command": "list",
  "version": "1.0.0",
  "data": {
    "type": "agents",
    "count": 10,
    "items": [
      { "name": "spec-writer",  "version": "1.0.0", "description": "Transforms plans into specs" },
      { "name": "implementer",  "version": "1.0.0", "description": "Implements from specifications" }
    ]
  },
  "errors": []
}

`omniskill search`

Search the OMNISKILL registry by keyword.

Usage

BASH

omniskill search <query> [--json]

Options

Option	Description
`<query>`	Required. Search term — matches name, description, tags, and triggers
`--json`	Output results as structured JSON

Example

$ omniskill search react
Search results for "react" (4 matches)
───────────────────────────────────────
  react-best-practices         skill    React hooks, patterns, and optimization
  vercel-react-best-practices  skill    Next.js and React performance from Vercel
  frontend-design              skill    Production-grade frontend interfaces
  web-dev-kit                  bundle   Includes react-best-practices + 4 more

$ omniskill search "game dev"
Search results for "game dev" (3 matches)
─────────────────────────────────────────
  godot-best-practices         skill    Godot 4.x GDScript best practices
  godot-gdscript-patterns      skill    Master Godot 4 GDScript patterns
  godot-kit                    bundle   Complete Godot game development kit

`omniskill info`

Show detailed information about a skill, bundle, agent, or pipeline.

Usage

BASH

omniskill info <name> [--json]

Options

Option	Description
`<name>`	Required. Name of the item to inspect
`--json`	Output results as structured JSON

Example

$ omniskill info react-best-practices
react-best-practices
━━━━━━━━━━━━━━━━━━━━
  Type:         skill
  Version:      1.0.0
  Author:       omniskill-team
  License:      MIT
  Platforms:    claude-code, copilot-cli, cursor, windsurf, antigravity
  Tags:         web, react, hooks, performance
  Priority:     P2
  Description:  React development guidelines with hooks, component
                patterns, state management, and performance optimization.

  Triggers:
    Keywords:   "react component", "react hooks", "use state"
    Patterns:   "create * react *", "optimize react *"

  Dependencies: none
  Bundle:       web-dev-kit

  Installed:    Yes (3 platforms)

`omniskill pipeline`

Run or check the status of multi-agent pipelines.

Usage

BASH

omniskill pipeline run <name> [--project <name>]
omniskill pipeline status [--project <name>]

Sub-commands

Sub-command	Description
`run <name>`	Start a pipeline by name
`status`	Show status of running / completed pipelines

Options

Option	Description
`--project <name>`	Associate the pipeline run with a project name

Examples

$ omniskill pipeline run sdd --project my-feature
✓ Starting SDD pipeline for project "my-feature"
  Phase 1/3: spec-writer        ▶ Running...
  Phase 2/3: implementer        ○ Pending
  Phase 3/3: reviewer           ○ Pending

$ omniskill pipeline status --project my-feature
Pipeline: sdd (my-feature)
──────────────────────────
  Phase 1/3: spec-writer        ✓ Complete    (2m 14s)
  Phase 2/3: implementer        ▶ Running     (1m 03s)
  Phase 3/3: reviewer           ○ Pending

$ omniskill pipeline status
Active Pipelines
────────────────
  sdd (my-feature)              Phase 2/3    implementer     Running
  ux-lifecycle (redesign)       Phase 5/7    ui-design       Running

`omniskill update`

Check for and apply updates to OMNISKILL.

Usage

BASH

omniskill update [--check]

Options

Option	Description
`--check`	Only check for updates without applying them

Example

$ omniskill update --check
Current version: v1.0.0
Latest version:  v1.1.0
Update available! Run `omniskill update` to install.

$ omniskill update
Updating OMNISKILL v1.0.0 → v1.1.0...
  ✓ Downloaded v1.1.0
  ✓ Updated CLI
  ✓ Migrated config (no changes needed)
  ✓ Re-validated installed skills
Update complete! Run `omniskill doctor` to verify.

`omniskill migrate`

Migrate legacy OMNISKILL skill files (pre-v1.0) to the current format.

Usage

BASH

omniskill migrate <path> [--in-place]

Options

Option	Description
`<path>`	Required. Path to the skill or directory to migrate
`--in-place`	Overwrite originals instead of creating `.migrated` copies

Example

$ omniskill migrate skills/old-skill
Migrating skills/old-skill...
  ✓ manifest.yaml → manifest.yaml.migrated    Added 'platforms' field
  ✓ SKILL.md → SKILL.md.migrated              Added 'When to Use' section
Migration preview complete. Review .migrated files, then run with --in-place.

$ omniskill migrate skills/old-skill --in-place
Migrating skills/old-skill (in-place)...
  ✓ manifest.yaml              Added 'platforms' field
  ✓ SKILL.md                   Added 'When to Use' section
Migration complete! Run `omniskill validate skills/old-skill` to verify.

`omniskill admin`

Administrative utilities — sync knowledge sources, rebuild indexes, and manage the registry.

Usage

BASH

omniskill admin

Example

$ omniskill admin
OMNISKILL Admin
───────────────
  1. Sync knowledge sources
  2. Rebuild skill index
  3. Clear platform caches
  4. Export installation report
  5. Reset configuration

Select an option [1-5]:

💡

Non-interactive usage

Pipe a selection for scripted environments: echo 1 | omniskill admin

`omniskill config`

Read or write OMNISKILL configuration values.

Usage

BASH

omniskill config [key] [value] [--list]

Options

Option	Description
`[key]`	Configuration key to read or set (dot-notation supported)
`[value]`	New value to assign to the key
`--list`	Show all configuration key-value pairs

Example

$ omniskill config --list
home             = ~/.omniskill
platforms        = claude-code, copilot-cli, cursor
default_bundle   = web-dev-kit
auto_update      = true
json_output      = false

$ omniskill config platforms
claude-code, copilot-cli, cursor

$ omniskill config auto_update false
✓ Set auto_update = false

🔢 Exit Codes

Code	Meaning	Used By
`0`	Success — command completed without errors	All commands
`1`	Error — runtime failure, missing dependency, etc.	All commands
`2`	Validation failure — one or more checks failed	`validate`, `doctor`

💡

CI/CD Tip

Use exit codes in your pipeline: omniskill validate || echo "Validation failed!"

⚙️ Configuration

Config File

OMNISKILL stores configuration in ~/.omniskill/config.yaml:

YAML

# ~/.omniskill/config.yaml
home: ~/.omniskill
platforms:
  - claude-code
  - copilot-cli
  - cursor
default_bundle: web-dev-kit
auto_update: true
json_output: false
log_level: info

Environment Variables

Environment variables override config file values:

Variable	Description	Default
`OMNISKILL_HOME`	Override the OMNISKILL home directory	`~/.omniskill`
`OMNISKILL_PLATFORM`	Force a specific platform (skip auto-detection)	auto-detected

$ OMNISKILL_HOME=/opt/omniskill omniskill doctor   # Custom home dir
$ OMNISKILL_PLATFORM=cursor omniskill install --all  # Force platform

🔍 Platform Detection

OMNISKILL auto-detects installed AI coding assistants by checking for platform-specific files and directories:

Platform	Detection Method
Claude Code	Checks for `~/.claude/` directory and `AGENTS.md`
Copilot CLI	Checks for `~/.copilot/` directory
Cursor	Checks for `~/.cursor/rules/` directory
Windsurf	Checks for `~/.windsurf/` or `~/.codeium/windsurf/`
Antigravity	Checks for `~/.antigravity/` directory

How It Works

On omniskill init, the CLI scans your system for each platform's indicator files.
Detected platforms are saved to ~/.omniskill/config.yaml.
On omniskill install, skills are deployed to each detected platform using the appropriate adapter.
Each adapter transforms a universal OMNISKILL skill into the platform's native format.

Override Detection

$ omniskill install --all --platform claude-code   # Flag override
$ export OMNISKILL_PLATFORM=cursor                  # Env var override
$ omniskill install --all

📋 JSON Output

When the --json flag is passed, all commands output a structured JSON envelope:

JSON

{
  "status": "ok",
  "command": "doctor",
  "version": "1.0.0",
  "data": {
    "checks_passed": 11,
    "checks_failed": 0,
    "checks_skipped": 2,
    "platforms": ["claude-code", "copilot-cli", "cursor"]
  },
  "errors": []
}

Envelope Fields

Field	Type	Description
`status`	`"ok"` \| `"fail"` \| `"error"`	Overall result
`command`	`string`	The command that was executed
`version`	`string`	OMNISKILL CLI version
`data`	`object`	Command-specific payload
`errors`	`array`	List of error messages (empty on success)

Error Envelope

JSON

{
  "status": "error",
  "command": "install",
  "version": "1.0.0",
  "data": null,
  "errors": [
    "Skill 'nonexistent-skill' not found in registry"
  ]
}

🐚 Shell Completions

Enable tab-completion for your shell:

$ omniskill --install-completion   # Auto-detects bash, zsh, fish, PowerShell

# Then restart your shell or source the completion file
$ source ~/.bashrc   # bash
$ source ~/.zshrc    # zsh

After installation, tab-complete commands, options, skill names, and bundle names:

$ omniskill ins<TAB>
install

$ omniskill install --sk<TAB>
--skill

$ omniskill install --skill react<TAB>
react-best-practices

🔄 Common Workflows

Install a Bundle

$ omniskill install --bundle web-dev-kit
$ omniskill doctor

Validate Before a PR

$ omniskill validate
# Exit code 0 = all good, 2 = validation failure

Check Installation Health

$ omniskill doctor --json | jq '.data.checks_failed'
0

Search and Install

$ omniskill search "django"
$ omniskill info django-expert
$ omniskill install --skill django-expert

Run a Pipeline

$ omniskill pipeline run sdd --project new-feature
$ omniskill pipeline status --project new-feature

Update OMNISKILL

$ omniskill update --check
$ omniskill update
$ omniskill doctor

🎯 Next Steps

Now that you know the CLI, explore these guides to go deeper:

🚀

CLI Guide for OMNISKILL

⚡ Installation

From PyPI (Recommended)

From Source

Verify Installation

🚀 Quick Start

🏳️ Global Flags

📖 Command Reference

omniskill init

Usage

Options

Example

omniskill install

Usage

Options

Examples

omniskill uninstall

Usage

Options

Example

omniskill doctor

Usage

Options

Example

omniskill validate

Usage

Options

Examples

omniskill list

Usage

Options

Examples

omniskill search

Usage

Options

Example

omniskill info

Usage

Options

Example

omniskill pipeline

Usage

Sub-commands

Options

Examples

omniskill update

Usage

Options

Example

omniskill migrate

Usage

Options

Example

omniskill admin

Usage

Example

omniskill config

Usage

Options

Example

🔢 Exit Codes

⚙️ Configuration

Config File

Environment Variables

🔍 Platform Detection

How It Works

Override Detection

📋 JSON Output

Envelope Fields

Error Envelope

🐚 Shell Completions

🔄 Common Workflows

Install a Bundle

Validate Before a PR

Check Installation Health

Search and Install

Run a Pipeline

Update OMNISKILL

🎯 Next Steps

Getting Started

`omniskill init`

`omniskill install`

`omniskill uninstall`

`omniskill doctor`

`omniskill validate`

`omniskill list`

`omniskill search`

`omniskill info`

`omniskill pipeline`

`omniskill update`

`omniskill migrate`

`omniskill admin`

`omniskill config`