immamdouhaboammar/omni-skill

Overview

OmniSkill is the industrial-grade, cross-host evolution of Anthropic's official skill-creator.

While baseline skill-creator provides basic prompt scaffolding for Claude alone, OmniSkill elevates skill creation into an autonomous, multi-agent engineering discipline powered by Poteto Mode (24 battle-tested engineering principles) and AgentSkills.io v1 Tripartite Architecture:

$$\text{Intent (Any Lang)} \longrightarrow \text{Dynamic DAG} \longrightarrow \text{Poteto Gates} \longrightarrow \text{BinEval Harness} \longrightarrow \text{Cross-Host Release}$$

What you can do

• Turn a repeated workflow or SOP into a skill with explicit decision rules.
• Evaluate activation boundaries, instruction quality, and pressure cases.
• Inspect skill code and resources with static security checks.
• Adapt the portable core to target hosts while recording capability gaps.
• Package reviewed skills and prepare distribution metadata.

Each result needs evidence appropriate to its claim. Static validation is not behavioral proof, and a test on one agent host does not verify another host.

ChatGPT and Codex plugin

The skills-only plugin provides guided setup and routes skill design, repair, evaluation, host adaptation, and packaging to focused workflows. It needs no MCP server or API key. File access and execution depend on the current host.

Build the upload archive from a checkout:

python3 scripts/plugin_package.py . /tmp/omni-skill-plugin.zip
python3 -m unittest discover -s tests -p 'test_plugin_*.py'

Upload the resulting ZIP at OpenAI Platform Plugins. Run Set Up OmniSkill after a test install. Start with “Turn this recurring workflow into a skill with clear triggers, decision rules, and evaluation cases.” The package includes portable plugin.json, a Codex compatibility manifest, 16 skills, and branding. Source development tests and CLI binaries stay outside this archive. Plugin package version 6.1.1 is separate from CLI version 6.1.0.

See submission preparation for host smoke cases, listing fields, and the publisher details still requiring portal confirmation. Local validation does not mean OpenAI approval or a tested installation.

Installation

1. Claude Code Native Marketplace

Inside Claude Code:

/plugin marketplace add imMamdouhaboammar/omni-skill
/plugin install omni-skill@imMamdouhaboammar

Or from your shell:

claude plugin marketplace add imMamdouhaboammar/omni-skill
claude plugin install omni-skill@imMamdouhaboammar

2. Vercel Skills CLI

npx skills add imMamdouhaboammar/omni-skill

3. Homebrew (macOS & Linux)

brew tap imMamdouhaboammar/omni-skill https://github.com/imMamdouhaboammar/omni-skill
brew install omni-skill

4. Global Bun / npm CLI

bun add -g @mamdouh-aboammar/omni-skill
# Or run ad-hoc
bunx @mamdouh-aboammar/omni-skill --help

Poteto Mode: The 24 Engineering Principles

OmniSkill embeds Cursor's and masseater's battle-tested 24 engineering principles directly into its core engine and skill library:

• attack-the-premise: Suspect the shared premise when multiple fixes fail.
• boundary-discipline: Consolidate validation at the perimeter; trust internal types unconditionally.
• build-the-lever: Replace manual repetition with rerunnable scripts and codemods.
• encode-lessons-in-structure: Turn recurring rules into linters, schemas, and validators.
• explain-the-number: Name the resource bounding every measured number ("why not double?").
• fix-root-causes: Trace defects to underlying mechanisms; never patch symptoms.
• make-operations-idempotent: Ensure commands converge correctly regardless of retries.
• migrate-callers-then-delete-legacy-apis: Eliminate old APIs in the same wave as new ones.
• model-the-domain: Make invalid states unrepresentable in domain data structures.
• prove-it-works: Check the real runtime directly; never rely on proxies or self-reports.
• subtract-before-you-add: Excise dead code, unused shims, and speculative scaffolding first.
• type-system-discipline: Model variants with discriminated unions; parse at boundaries.

See skills/poteto-principles for all 24 principles.

Skills Suite

OmniSkill includes fifteen modular, certified sub-skills:

1. Engineering Discipline Suite

2. Autonomous Toolchain & Lifecycle Suite

⚡ Dynamic Agentic Router

flowchart TD
    A["User Prompt (Any Language)"] --> B["OmniSkill Agentic Router"]
    B --> C["Host Capability Negotiation"]
    B --> D["Intent Classifier (12 Modes)"]
    C --> E["Dynamic Execution DAG"]
    D --> E
    
    subgraph ExecutionPipeline ["Autonomous Skill Pipeline"]
        F["1. Authoring Standard (skill-authoring)"]
        G["2. Poteto Discipline (poteto-principles)"]
        H["3. Empirical Benchmark (measure-dont-guess)"]
        I["4. Integration Migration (integrate)"]
        J["5. Behavioral Evals (skill-evaluator)"]
        K["6. 7-Pass Validation (omni-skill validate)"]
        L["7. Multi-Host Ports (skill-portability-compiler)"]
    end
    
    E --> ExecutionPipeline
    ExecutionPipeline --> M["Release-Ready Skill Artifact"]

CLI Usage

# 1. Dynamic Agentic Router
omni-skill route "integrate drizzle orm and migrate prisma" --explain
omni-skill route "benchmark latency before optimizing" --explain
omni-skill route "قيس السرعة قبل التعديل" --explain

# 2. Initialize a new tripartite skill package
omni-skill init my-skill -d "High performance query optimizer"

# 3. Run the 7-pass static validator
omni-skill validate skills/omni-skill
omni-skill validate skills/poteto-principles

# 4. Port a skill to any AI agent (Claude, Cursor, Codex, Windsurf, Antigravity)
omni-skill port examples/sql-optimizer --target cursor
omni-skill port examples/sql-optimizer --target claude
omni-skill port examples/sql-optimizer --target codex

# 5. Run BinEval test harness (with candidate response or per-case evidence)
omni-skill eval examples/sql-optimizer --candidate "Use EXPLAIN to inspect query plans and verify index usage."
omni-skill eval examples/sql-optimizer --responses examples/sql-optimizer/evals/responses.json --json

Testing & Quality Assurance

# Run Bun unit test suite
bun test

# Run Python core engine tests
python3 packages/core/test_engine.py

# Run 7-pass validation across all skills
for s in skills/*; do bun run packages/cli/src/index.ts validate "$s"; done

License

Distributed under the MIT License. See PRIVACY.md, TERMS.md, and SUPPORT.md.