Skip to content

usage

Jump to bottom
Moataz Mohamed edited this page Jun 24, 2026 · 1 revision

Usage Guide

The omni-skills CLI

Command Does
omni-skills mcp Run the MCP server over stdio (what each tool launches).
omni-skills index Regenerate INDEX.md files and the managed SHARED.md skill block.
omni-skills workflow [list|run <name>] List chainable skill workflows or run one.
omni-skills sync [tool|all] [--dry-run] Wire instructions, skills dirs, MCP config, hooks, and assets.
omni-skills check [--move] [--dry-run] Find orphaned skills and dangling/foreign symlinks.
omni-skills classify [path] [--depth=N] [--dry-run] Scan for instruction files, detect sensitive content, sort public/private.
omni-skills discover Scan your entire system for AI tools, instruction files, skill directories, and projects.
omni-skills setup Auto-scan system, detect tools, suggest cleanup, generate config.
omni-skills doctor Health check: verify symlinks, config, indexes, and skill counts.
omni-skills report [--enhance] Usage statistics and heuristic improvement tips.
omni-skills init [--dry-run] Interactive setup: scan, classify, route, wire.
omni-skills security [scan] Check/install NVIDIA SkillSpector. Scan skills for vulnerabilities.
omni-skills create [name] Create a new skill with interactive wizard.
omni-skills create from <file> Convert an existing file into a skill.
omni-skills help Show help.

Quick Start

# 1. Run the auto-scan setup
omni-skills setup
# Auto-detects your installed AI tools, finds your skill directories,
# suggests cleanup, and generates ~/.config/skills/config.json

# 2. Sync to every AI tool
omni-skills sync all

# 3. Verify health
omni-skills doctor

# 4. Run the verification suite
node verify.js

Setup Flags

# Override defaults without questions
omni-skills setup --public=~/my-skills-public --private=~/my-skills-private
omni-skills setup --toolkit=/path/to/this/repo

How I Use This (Real Stats)

My personal setup — after unifying:

Metric Value
AI tools wired 9 (Claude, Codex, Kimi, Gemini, Cursor, Kilocode, OpenCode, Windsurf, Claude Desktop)
Skills in canonical store 49 (all private, all mine)
Stale template files deleted 77 — eliminated duplicate AGENTS.md/GEMINI.md copies
Orphaned skills rescued 15 — from ~/.kimi/skills/ to canonical store
Duplicate skills removed 15 — from a project's marketplace clone
Generic marketplace skills archived 203 — removed from active project, not lost
Weekly health check Auto-runs omni-skills doctor every Sunday at 9:17 AM
Instruction files moved to canonical 5 — project-specific rules, no more drift
Core project rules 98KB file, single source, symlinked to 2 other repos
New tool onboarding omni-skills sync <tool> — one command

Weekly Health Check

A scheduled cron job runs omni-skills doctor every Sunday morning to catch drift before it becomes a problem:

omni-skills doctor    # Check all symlinks, config, indexes
omni-skills check     # Scan for orphaned skills
omni-skills report    # Usage stats and improvement tips

Verification

Before trusting the system, verify it:

node verify.js
# === Skills Ecosystem Verification ===
# [config]        ✓ loads successfully
# [skill paths]   ✓ 2 paths exist
# [skills scan]   ✓ 49 skills found, no duplicates
# [skill files]   ✓ all files valid
# [SHARED.md]     ✓ exists
# [instruction]   ✓ 6 symlinks + 1 regular valid
# [skills dirs]   ✓ 4 tools, 49 skills each, all healthy
# [MCP configs]   ✓ 7 tools, all have skills server
# ✓ ALL CHECKS PASSED (24 passed)

Tests

npm test

28 tests, Node's built-in runner, no extra dependencies. Covers:

  • sensitive.js — denylist detection (company names, ticket IDs, API keys, internal URLs)
  • fs-utils.js — symlink management, managed block insertion/updates
  • skills.js — skill scanning, frontmatter parsing, hidden directory filtering

CI runs on every push via GitHub Actions.

Documentation index

Documentation

Project links

Clone this wiki locally