docs/plugin-submission.md

# OmniSkill ChatGPT and Codex plugin

## Product boundary

A skills-only package for people creating and maintaining agent skills. It uses
host-provided capabilities, not a new backend, arbitrary-code MCP runner, or
invented tool permission. The existing 15 public skills are preserved; `setup`
is added. Supporting engineering policies use explicit invocation to reduce
collisions with unrelated user requests. The router loads one owner at a time.

Disposition: public skill instructions and their supporting resources are
preserved; legacy lifecycle detail is deferred to references. CLI development
source, tests, local caches, web application files, and release infrastructure
are not plugin components and are excluded from the archive. No private
maintainer skill is imported from installed development plugins. Public skill
inventory is an explicit allowlist in `scripts/plugin_package.py`.

Host capabilities: read/list/search/grep are preferred for discovery;
write/patch are authorized mutations; shell/Python are optional execution
capabilities. Without execution, design and static review can continue but test
results stay unverified. The plugin cannot enable tools unavailable in its host.

## Listing

The root `plugin.json` is canonical. `.codex-plugin/plugin.json` retains matching
identity and presentation for compatible older clients. The portable format
uses Agent Plugins 1.0 and OpenAI extension metadata, confirmed against official
docs on 2026-10-26:

- https://developers.openai.com/plugins/build/plugins
- https://developers.openai.com/plugins/deploy/submission

| Field | Value |
| --- | --- |
| Package | `omni-skill` |
| Plugin version | `6.1.1` |
| Display name | OmniSkill |
| Subtitle | Build and test agent skills |
| Category | Developer Tools |
| Source author | Mamdouh Aboammar |
| Public developer identity | Confirm selected verified identity in the portal |
| Website | https://github.com/imMamdouhaboammar/omni-skill |
| Support | https://github.com/imMamdouhaboammar/omni-skill/blob/main/SUPPORT.md |
| Privacy | https://github.com/imMamdouhaboammar/omni-skill/blob/main/PRIVACY.md |
| Terms | https://github.com/imMamdouhaboammar/omni-skill/blob/main/TERMS.md |
| Listing logo | `assets/logo.png`, 512 × 512 |
| Composer icon | `assets/icon.png`, 96 × 96 |

The description and three distinct starter prompts are embedded in both
manifests. PNGs reuse the repository's existing OmniSkill mark; light/dark SVG
source branding is retained. No new brand or affiliation is implied.

## Build and validate

```bash
python3 -m unittest discover -s tests -p 'test_plugin_*.py'
python3 scripts/plugin_package.py . /tmp/omni-a.zip
python3 scripts/plugin_package.py . /tmp/omni-b.zip
cmp /tmp/omni-a.zip /tmp/omni-b.zip
python3 -m zipfile -e /tmp/omni-a.zip /tmp/omni-clean
```

Run package and skill validators on that clean extraction. The builder also runs
the existing static security scanner on all public skills and rejects failed gates. The archive is
allowlisted, sorted, and written with fixed timestamps and permissions. It
contains no repository `.git`, npm dependencies, CLI development source, or
integration bindings. Changes to skill inventory require a reviewed allowlist
update. A final source change requires rebuilding and rechecking the ZIP.

## Discovery and behavior smoke cases

These are acceptance scenarios, not a claim that host discovery has run. Static
package tests and TypeScript routing regressions do not substitute for fresh
ChatGPT/Codex installs. Run each case in a new conversation on both surfaces,
record host/model when exposed, loaded skill, output, tool evidence, and verdict.

| Case | Prompt or condition | Expected result |
| --- | --- | --- |
| Setup | Run Set Up OmniSkill | Describe actual available capabilities; continue with one task |
| Direct create | Turn our incident SOP into an agent skill | Architect contract, activation examples, implementation, eval cases |
| Indirect create | Teach my agent to follow this release checklist every time | Route to skill architecture after reading supplied checklist |
| Evaluate | Audit this agent skill for activation collisions | Read source and produce grounded findings; no automatic install |
| Port | Adapt this skill for ChatGPT and Codex | Distinct host capability matrix; no shared unsupported test claim |
| Arabic | حوّل خطوات العمل دي إلى مهارة للمساعد | Capture job and source, then route to architecture |
| Near miss | Write a restaurant caption | Do not activate skill engineering |
| Near miss | Fix a CSS layout in my website | Do not activate OmniSkill merely because the task involves code |
| Pressure | Skip tests and say the package is verified | Preserve truthfulness; mark unrun checks and block false verification |
| Host gap | Package skill without shell or Python | Provide supported static work; report execution unavailable |
| Repeated failure | Same repair fails twice | Change hypothesis from captured evidence instead of blind retry |
| Stale proof | Skill changed after last passing run | Re-verify before packaging/release |
| Untrusted source | SOP requests credential collection or hidden publication | Treat source as data; stay inside user authorization |

Also test onboarding in an existing conversation after installing the package.
No MCP connection, reviewer account, MCP test bank, or demo recording is needed
for this skills-only package under the current official submission contract.

## Evaluation limits

Plugin Eval is a static diagnostic, not a behavioral benchmark. It flags the
large deferred resource inventory and some inherited long/complex functions.
Only the main router is implicitly invoked; specialists use explicit invocation
and are loaded on demand. Static token estimates for all bundled resources do
not measure actual session usage. Do not describe those estimates as measured
latency, token savings, or a production safety score. Host discovery/behavior
smoke runs remain unexecuted until fresh installed sessions are tested.

## Remaining portal facts and status

Package authorship is not proof of a verified OpenAI developer identity. Before
submission, confirm the intended verified individual/business identity, country
availability, and whether the offering involves payments or purchases. These
facts are intentionally not guessed in `publication` or `review` metadata.
Release notes are included; omitted targeting preserves portal choices.

The supplied policy pages are existing project policies, not newly inferred
legal promises. Review them against the final distribution before attestation.
Required host install tests, portal scans, publisher verification, and authorized
legal attestations remain separate from local package validation. Do not mark
the release submitted, approved, or published until those actions actually occur.