# 📖 Omni Skills — Documentation Hub > **The central reference for using, operating, extending, and understanding the current Omni Skills platform.** Standard community files live in the repository root: [`README.md`](../README.md) · [`CONTRIBUTING.md`](../CONTRIBUTING.md) · [`SECURITY.md`](../SECURITY.md) · [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) --- ## 📊 Status Snapshot | Area | State | Details | |:-----|:------|:--------| | 🏗️ **Runtime** | ✅ Current | Unified CLI, Ink visual shell, API, MCP, and A2A all ship from the same package | | 📦 **Catalog** | 📌 55 skills | 55 native catalog skills across 15 active categories, with 32 curated English derivatives in `skills_omni/` and 7 fully backed bundles | | 🎯 **Install** | ✅ Current | Guided TTY install, selective `--skill` and `--bundle`, custom path support, and discovery-driven install | | 🌐 **API** | ✅ Current | Read-only registry API with auth, admin runtime, rate limiting, CORS/IP allowlists, maintenance mode, and downloads | | 🔌 **MCP** | ✅ Current | `stdio` · `stream` · `sse`, local sidecar mode, 7 install-capable clients, 16 config-capable clients, 33 config targets, and 19 config profiles | | 🤖 **A2A** | ✅ Current | Simple-first local runtime with JSON/SQLite durability, restart resume, SSE streaming, cancelation, external executor mode, and optional leased coordination when explicitly enabled | | 🛡️ **Security** | ✅ Current | Static scanner, optional ClamAV/VirusTotal, signed release artifacts, archive checksums, and release-time verification | | 📋 **Classification** | ✅ Current | Canonical taxonomy, maturity, semantic quality spread, best-practices spread, and security scoring | | 📁 **Archives** | ✅ Current | Per-skill `.zip` and `.tar.gz` archives with SHA-256 checksum manifests | | 🔐 **Signing** | ✅ Current | Detached signatures enforced on release tags; local install flows consume the same manifest and checksum metadata | | 🧬 **Intake Flow** | ✅ Current | Native skills land under `skills/` through direct contributor PRs and automated external-import PRs; PR automation reviews them and proposes Omni-enhanced derivatives under `skills_omni/` | ## 🔭 Current Project State The foundation track now lives in the active project state, and the second category-expansion wave is already in the catalog. The project should now be read as a working baseline with optional future expansion tracks: - public `v0.1.5` and private `v1.0.0` are the current stable release floor - the catalog now covers 55 native skills across 15 active categories, with 45 passing validation cleanly and 10 currently in warning-grade native intake - curated `skills_omni/` output remains a maintained English-only surface with 32 automation-managed derivatives - protocol surfaces, release automation, and private enhancement automation are in service, not in bootstrap - the private external-sync runtime is now actively proposing native intake through `external-import/*` PRs, using the same public validator and enhancer path as human-submitted native PRs Future expansion stays deliberate: - deepen `design`, `tools`, `data-ai`, and `machine-learning` - avoid reopening dormant non-code-native categories until the current code-native tracks have stronger depth - keep the quality floor and enhancer review path intact while doing so That expansion work is now reflected directly in the live catalog and architecture docs: - the current catalog snapshot in [Catalog](CATALOG.md) - the runtime and artifact shape in [Codebase Analysis](architecture/CODEBASE-ANALYSIS.md) - the forward direction in [Agent-Native Roadmap](architecture/AGENT-NATIVE-ROADMAP.md) --- ## 📌 Current Decisions These architecture questions are no longer “open” in practice and are now treated as project decisions: 1. **Distribution stays manifest-first plus signed archives** The machine-readable manifest remains the contract consumed by CLI, API, MCP, and A2A. Signed per-skill archives are the download and release surface layered on top of that contract. 2. **Private or premium catalogs should reuse the same manifest schema** Auth and policy should be layered externally, not by forking the manifest or catalog shape. 3. **MCP config should converge on a few canonical export families** Omni Skills now standardizes around JSON `mcpServers`, JSON `servers`, JSON `context_servers`, YAML `mcpServers`, YAML `extensions`, and TOML `[mcp_servers]`, while keeping bespoke writers only where official client docs require a different structure. Those decisions align with current official MCP and client documentation, including: - official MCP Registry and extension support guidance at `modelcontextprotocol.io` - OpenAI Docs MCP and Codex CLI docs at `developers.openai.com` and `platform.openai.com` - VS Code MCP extension and product docs at `code.visualstudio.com` - client docs for Claude Code, Cursor, Continue, Junie, Kiro, OpenCode, Cline, Kilo Code, GitHub Copilot CLI, Zed, Goose, Postman, and JetBrains AI Assistant --- ## 🚀 Start Here ### 👤 If You Want to **Use** the Project | Doc | What You'll Learn | |:----|:------------------| | 📘 [Getting Started](users/GETTING-STARTED.md) | Install, verify, and invoke your first skill | | 🧭 [CLI User Guide](users/CLI-USER-GUIDE.md) | Full command reference and real-world CLI usage patterns | | 📗 [Usage Guide](users/USAGE.md) | CLI commands, install modes, runtime commands, and MCP config flows | | 📦 [Bundles](users/BUNDLES.md) | Curated bundles and their current availability | | 📚 [Catalog](CATALOG.md) | Auto-generated catalog of published skills | | 🔧 [System Runbook](operations/RUNBOOK.md) | Build, serve, secure, and troubleshoot the runtime | ### 🏗️ If You Want to **Understand** the Runtime | Doc | What You'll Learn | |:----|:------------------| | 🗺️ [Agent-Native Roadmap](architecture/AGENT-NATIVE-ROADMAP.md) | Architecture evolution, closed decisions, and remaining expansion areas | | 🧭 [CLI UX Roadmap](architecture/CLI-UX-ROADMAP.md) | Historical plan and current shape of the guided and visual CLI | | 📐 [ADR-0001: Workspace Foundation](architecture/ADR-0001-AGENT-NATIVE-WORKSPACE.md) | Core monorepo and shared-runtime decision | | 🔬 [Codebase Analysis](architecture/CODEBASE-ANALYSIS.md) | Current runtime composition, counts, and system boundaries | | 🌐 [Catalog API Surface](specs/CATALOG-API.md) | HTTP endpoints, filtering, governance, and downloads | | 🧩 [CLI Guided Installer](specs/CLI-GUIDED-INSTALLER.md) | Behavioral contract for the guided installer | | 🖥️ [CLI Visual Shell](specs/CLI-VISUAL-SHELL.md) | Ink visual shell, state model, and service hub | | 🔌 [Local MCP Sidecar](specs/LOCAL-MCP-SIDECAR.md) | Filesystem-aware tools, allowlist model, and config writing | | 🧭 [Client Support Matrix](specs/CLIENT-SUPPORT-MATRIX.md) | Supported CLI and IDE clients, writers, manual targets, and source references | | 📊 [Skill Classification](specs/SKILL-CLASSIFICATION.md) | Taxonomy, scoring heuristics, and metadata artifacts | | 🛡️ [Security Validation](specs/SECURITY-VALIDATION.md) | Scanners, archives, signatures, and release verification | | 📋 [Skill Manifest Spec](specs/SKILL-MANIFEST.md) | Machine-readable manifest format and compatibility contract | ### 🤝 If You Want to **Contribute** | Doc | What You'll Learn | |:----|:------------------| | 📝 [Contributing Guide](../CONTRIBUTING.md) | Repo workflow and pull request expectations | | 🧾 [Skill PR Workflow](contributors/SKILL-PR-WORKFLOW.md) | Native intake, automatic enhancer processing, `skills_omni/` publishing, and reviewer expectations | | 📄 [Skill Template](contributors/SKILL-TEMPLATE.md) | Starter `SKILL.md` with current frontmatter and structure | | 🔬 [Skill Anatomy](contributors/SKILL-ANATOMY.md) | Structure and quality expectations for a skill | | ✅ [Quality Bar](contributors/QUALITY-BAR.md) | Acceptance criteria for the repository | | 🏆 [High-Score Playbook](contributors/HIGH-SCORE-PLAYBOOK.md) | What drives high maturity, quality, best-practices, and security scores | --- ## 🔌 Runtime Surfaces ### 🖥️ CLI ```bash npx omni-skills # Guided install in TTY npx omni-skills install --guided # Forced guided install npx omni-skills ui # Ink visual shell npx omni-skills ui --text # Text fallback UI ``` The published `omni-skills` binary is the unified public entry point. ```bash # 🔎 Discovery npx omni-skills find figma npx omni-skills find mcp --sort quality --min-quality 90 --min-security 95 npx omni-skills find figma --tool cursor --install --yes # 📦 Installation npx omni-skills install --guided --path ./my-skills --skill architecture npx omni-skills --cursor --skill omni-figma npx omni-skills --codex --bundle full-stack # ⚙️ MCP config npx omni-skills config-mcp --list-targets npx omni-skills config-mcp --target continue-workspace --transport stream --url http://127.0.0.1:3334/mcp npx omni-skills config-mcp --target junie-project --transport stream --url http://127.0.0.1:3334/mcp npx omni-skills config-mcp --target windsurf-user --transport sse --url http://127.0.0.1:3335/sse --write npx omni-skills config-mcp --target copilot-user --transport stream --url http://127.0.0.1:3334/mcp --write # 🏷️ Taxonomy npx omni-skills recategorize npx omni-skills recategorize --write # 🔌 Services npx omni-skills mcp stream --local npx omni-skills api --port 3333 npx omni-skills a2a --port 3335 # 🧪 Validation npx omni-skills smoke npx omni-skills doctor ``` For the complete end-user command surface, use [CLI User Guide](users/CLI-USER-GUIDE.md). ### 📁 Generated Artifacts The build pipeline emits the machine-readable files that drive every runtime surface: | Artifact | Purpose | |:---------|:--------| | `metadata.json` | Repository-wide validation and score summary | | `skills_index.json` | Repo-local normalized skill index | | `dist/catalog.json` | Published catalog for search and listing | | `dist/bundles.json` | Bundle definitions with availability | | `dist/manifests/.json` | Per-skill machine-readable manifest | | `dist/archives/.zip` | Skill archive (zip) | | `dist/archives/.tar.gz` | Skill archive (tarball) | | `dist/archives/.checksums.txt` | SHA-256 checksum manifest | `dist/` stays committed on purpose. These generated artifacts are part of the install, API, MCP, A2A, smoke, and release contract. ### 🌐 API ```bash npx omni-skills api --port 3333 ``` Read-only registry API for skills, bundles, comparison, install planning, and artifact downloads. ### 🔌 MCP ```bash npx omni-skills mcp stdio npx omni-skills mcp stream npx omni-skills mcp sse npx omni-skills mcp stream --local ``` The local sidecar now supports first-class MCP config writing for: - Claude Code - Cursor - VS Code and Dev Containers - Gemini CLI - Antigravity - Kiro - Codex CLI - Continue - Windsurf - OpenCode - Cline - GitHub Copilot CLI - Kilo Code - Zed - Goose ### 🤖 A2A ```bash npx omni-skills a2a --port 3335 ``` Task lifecycle, streaming, persistence, restart recovery, and simple-first local orchestration. Shared leased execution is available when explicitly enabled; Redis remains an advanced hosted option, not the default local path. --- ## 🗂️ Repository Map | Path | Purpose | |:-----|:--------| | 📂 `skills/` | Canonical authored skills | | 📖 `docs/users/` | End-user documentation | | 🤝 `docs/contributors/` | Contributor templates and guidance | | 🏗️ `docs/architecture/` | Roadmap, ADRs, and technical analysis | | 🔧 `docs/operations/` | Operational runbooks | | 📋 `docs/specs/` | Runtime, protocol, and artifact contracts | | 📚 `docs/CATALOG.md` | Generated skill catalog | | 📦 `dist/` | Generated machine-readable artifacts | | 🧠 `packages/catalog-core/` | Shared catalog runtime | | 🌐 `packages/server-api/` | Read-only HTTP API | | 🔌 `packages/server-mcp/` | MCP server and local sidecar | | 🤖 `packages/server-a2a/` | A2A server and task runtime | | 🖥️ `tools/bin/` | CLI entry points | | 📚 `tools/lib/` | Installer and UI helpers | | ⚙️ `tools/scripts/` | Validation, generation, verification, and tests | --- ## 🧪 Release Validation ```bash npm run smoke ``` The smoke run validates: - ✅ skill validation and metadata generation - ✅ taxonomy recategorization tooling - ✅ catalog artifact generation - ✅ generated catalog markdown - ✅ archive generation and verification - ✅ automated test suite - ✅ `npm pack --dry-run` - ✅ API boot and health - ✅ MCP boot in `stdio`, `stream`, and `sse` - ✅ A2A boot, polling, SSE streaming, cancelation, and push-config lifecycle