Add Codex plugin compatibility (#16)

* Add Codex plugin compatibility

* docs: clarify shared Claude and Codex support

Author: DudiPeretz-Orca

.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "orcasecurity",
+  "interface": {
+    "displayName": "Orca Security"
+  },
+  "plugins": [
+    {
+      "name": "orca-skills",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Security"
+    }
+  ]
+}

.codex-plugin/plugin.json

@@ -0,0 +1,51 @@
+{
+  "name": "orca-skills",
+  "version": "2.0.0",
+  "description": "Orca Security skills collection for cloud security workflows with the Orca Cloud Platform.",
+  "author": {
+    "name": "Orca Security",
+    "email": "support@orca.security",
+    "url": "https://orca.security"
+  },
+  "homepage": "https://github.com/orcasecurity/orca-skills",
+  "repository": "https://github.com/orcasecurity/orca-skills",
+  "license": "MIT",
+  "keywords": [
+    "security",
+    "orca",
+    "triage",
+    "alerts",
+    "soc",
+    "incident-response",
+    "cloud-security",
+    "compliance",
+    "identity",
+    "exposure",
+    "dspm",
+    "investigation",
+    "asset-profile",
+    "codex",
+    "claude",
+    "cursor",
+    "mcp"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Orca Security Skills",
+    "shortDescription": "Cloud security workflows powered by Orca MCP data.",
+    "longDescription": "Install Orca Security skills for alert triage, impact analysis, compliance gaps, exposure mapping, incident investigation, cloud cost optimization, and daily security briefings.",
+    "developerName": "Orca Security",
+    "category": "Security",
+    "capabilities": [
+      "Security Analysis",
+      "Cloud Security",
+      "MCP"
+    ],
+    "defaultPrompt": [
+      "Give me an Orca morning briefing.",
+      "Triage Orca alert orca-1234567.",
+      "Show my external exposure map."
+    ],
+    "brandColor": "#00D4AA"
+  }
+}

.codex/plugin.json

@@ -1,14 +1,14 @@
 {
-  "name": "orca-triage",
-  "displayName": "Orca Security Alert Triage",
-  "description": "Triage Orca Security alerts with analyst-friendly formatting, timeline analysis, and progressive disclosure",
-  "version": "1.0.0",
+  "name": "orca-skills",
+  "displayName": "Orca Security Skills",
+  "description": "Skills and plugins to accelerate security workflows with the Orca Cloud Platform",
+  "version": "2.0.0",
   "author": {
     "name": "Orca Security",
     "email": "support@orca.security"
   },
-  "homepage": "https://github.com/orca-security/orca-triage-skill",
-  "repository": "https://github.com/orca-security/orca-triage-skill",
+  "homepage": "https://github.com/orcasecurity/orca-skills",
+  "repository": "https://github.com/orcasecurity/orca-skills",
   "license": "MIT",
   "keywords": [
     "security",
@@ -17,7 +17,18 @@
     "alerts",
     "soc",
     "incident-response",
-    "threat-intelligence"
+    "threat-intelligence",
+    "cloud-security",
+    "compliance",
+    "identity",
+    "exposure",
+    "dspm",
+    "investigation",
+    "asset-profile",
+    "codex",
+    "claude",
+    "cursor",
+    "mcp"
   ],
   "skills": "./skills/",
   "mcp_required": [

.cursor-plugin/plugin.json

@@ -0,0 +1,27 @@
+name: Packaging
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: packaging-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: packaging (node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 24]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm test

.github/workflows/validate-packaging.yml

@@ -22,7 +22,7 @@ If a skill produces unexpected output, fails to trigger, or behaves incorrectly:
    - The skill name (e.g., `orca-alert-triage`)
    - The exact prompt or input you used
    - What you expected vs. what you got
-   - Your Claude Code version (`claude --version`) and OS
+   - Your client and version (`claude --version` or `codex --version`) and OS
    - Any error output or unexpected MCP behavior
 
 > For security vulnerabilities, **do not open a public issue**. See [SECURITY.md](SECURITY.md).
@@ -43,13 +43,22 @@ This avoids wasted effort and keeps the repo focused.
 
 ## Development Setup
 
+Skills are plain Markdown files under `skills/<skill-name>/SKILL.md`. There is no build step or runtime dependency to author them. Node.js 20+ is required to run the repository packaging checks.
+
 ```bash
 # Fork and clone
 git clone https://github.com/<your-username>/orca-skills.git
 cd orca-skills
+
+# Validate plugin packaging and run regression tests
+npm test
 ```
 
-Skills are plain Markdown files under `skills/<skill-name>/SKILL.md` — no build step or runtime is required to author or modify them. Install them via the Claude Code plugin marketplace (see [README](README.md)) to try them locally.
+Claude, Cursor, and Codex all use this single root `skills/` tree. Edit it once; do not create copies under `plugins/orca-skills/`. `npm test` checks the plugin manifests, marketplace sources, and skill metadata. With Codex CLI installed, `npm run test:codex` also verifies installation and discovery in a temporary home. See [README](README.md#testing).
+
+Keep shared skill instructions usable in both Claude and Codex. Label client-specific setup commands and usage examples clearly.
+
+The independent `security-engineer` plugin has its own [development setup and test suite](plugins/security-engineer/README.md#developing).
 
 **Note:** `.mcp.json` is gitignored. Never commit API tokens or credentials.
 
@@ -64,7 +73,7 @@ Skills are plain Markdown files under `skills/<skill-name>/SKILL.md` — no buil
    git checkout -b docs/update-readme
    ```
 
-2. **Make your changes.** Edit or add `SKILL.md` files under `skills/<skill-name>/`.
+2. **Make your changes.** Edit or add `SKILL.md` files under `skills/<skill-name>/`. Run `npm test` before pushing; the packaging workflow runs it on every pull request.
 
 3. **Keep PRs focused.** One bug fix or one new skill per PR. Do not bundle unrelated changes.
 
@@ -77,9 +86,10 @@ Skills are plain Markdown files under `skills/<skill-name>/SKILL.md` — no buil
 5. **PR description** must include:
    - What changed and why
    - A link to the related issue (if applicable)
-   - For new skills: a brief validation note (did you test with a real Orca environment?)
+   - Confirmation that `npm test` passes locally
+   - For new skills: a brief Claude and/or Codex validation note, including whether you tested with a real Orca environment
 
-6. **One approving review** from a maintainer is required to merge.
+6. **CI must pass**, and one approving review from a maintainer is required to merge.
 
 ---
 

CONTRIBUTING.md

@@ -14,11 +14,15 @@
 
 ---
 
+Orca Skills supports both **Claude Code and Codex**. Both clients use the same
+`skills/` directory, with separate plugin manifests and installation instructions.
+
 ### Table of Contents
 - [Plugins](#plugins)
 - [Skills Overview](#skills-overview)
 - [Installation](#installation)
 - [MCP Configuration](#mcp-configuration)
+- [Usage Notes](#usage-notes)
 - [Skill Details](#skill-details)
 - [Testing](#testing)
 - [Contributing](#contributing)
@@ -34,7 +38,7 @@ people want the first one.
 
 | Plugin | What it is | Prerequisites |
 |---|---|---|
-| [`orca-skills`](#skills-overview) | 16 read-only skills that answer questions about your cloud environment through the Orca MCP server | The Orca MCP server. Nothing else |
+| [`orca-skills`](#skills-overview) | 20 skills for cloud security analysis and guided remediation through the Orca MCP server | The Orca MCP server. Nothing else |
 | [`security-engineer`](plugins/security-engineer/) | An autonomous agent that **remediates** Orca findings in your source code and opens a pull request per fix | Python 3.10+, authenticated [`gh`](https://cli.github.com/), `ORCA_API_TOKEN` in the environment, network access to OSV.dev and deps.dev |
 
 They answer different questions and are kept apart on purpose: `orca-skills`
@@ -97,14 +101,23 @@ second plugin or any of its prerequisites.
 Then install whichever plugins you want:
 
 ```bash
-claude plugin install orca-skills@orcasecurity          # the 16 MCP skills
+claude plugin install orca-skills@orcasecurity          # the MCP skills
 claude plugin install security-engineer@orcasecurity    # autonomous remediation
 ```
 
 **Next step:** Configure the Orca Security MCP server (see [MCP Configuration](#mcp-configuration) below).
 `security-engineer` does not use MCP — its setup is in
 [its own README](plugins/security-engineer/README.md).
 
+### Codex CLI
+
+```bash
+codex plugin marketplace add orcasecurity/orca-skills
+codex plugin add orca-skills --marketplace orcasecurity
+```
+
+This installs `orca-skills` from the root `skills/` directory. Configure the Orca Security MCP server using the [Codex instructions](#codex-mcp-configuration) below. The separate `security-engineer` plugin uses Claude Code; see [its README](plugins/security-engineer/README.md).
+
 ### Claude Desktop
 
 Add the marketplace to your Claude Desktop configuration, then install skills from the marketplace UI.
@@ -118,12 +131,18 @@ cd orca-skills
 
 # Copy skills to your skills directory
 cp -r skills/* ~/.claude/skills/
+
+# Or install into Codex's user skills directory
+mkdir -p ~/.agents/skills
+cp -r skills/* ~/.agents/skills/
 ```
 
 ## MCP Configuration
 
 **Required:** These skills need the Orca Security MCP server to access your environment data.
 
+### Claude Code / Claude Desktop
+
 Add to your `.mcp.json` (in project root or `~/.claude/.mcp.json`):
 
 **Uses OAuth2 for authentication**
@@ -164,6 +183,42 @@ Add to your `.mcp.json` (in project root or `~/.claude/.mcp.json`):
 > `.mcp.json`. Configuring one does not configure the other.
 
 
+### Codex MCP Configuration
+
+For OAuth2 authentication:
+
+```bash
+codex mcp add orca-security --url https://mcp.orcasecurity.io
+codex mcp login orca-security
+```
+
+For token based authentication, set the authorization value in an environment variable:
+
+```bash
+export ORCA_AUTHORIZATION="Token YOUR_ORCA_API_TOKEN"
+```
+
+Reference the variable in `~/.codex/config.toml` (or `$CODEX_HOME/config.toml` when using a custom home):
+
+```toml
+[mcp_servers.orca-security]
+url = "https://api.orcasecurity.io/mcp"
+env_http_headers = { Authorization = "ORCA_AUTHORIZATION" }
+```
+
+Check the connection with `codex mcp list`. See the [official Codex MCP documentation](https://developers.openai.com/codex/mcp/).
+
+## Usage Notes
+
+Claude examples use slash commands such as `/orca-alert-triage`. In Codex, use natural language or explicitly mention the installed skill:
+
+```text
+triage Orca alert orca-1234567
+$orca-skills:orca-morning-briefing what needs attention today?
+```
+
+For a manually copied skill, use its standalone name, such as `$orca-morning-briefing`.
+
 ## Skill Details
 
 <details>
@@ -1440,6 +1495,32 @@ ADMIN GROUPING SUMMARY  (window: last 90 days; artifact: daily snapshot)
 
 </details>
 
+## Testing
+
+With Node.js 20+ installed, run the packaging validation and regression tests:
+
+```bash
+npm test
+```
+
+These dependency-free checks validate the Claude, Cursor, and Codex manifests, the marketplace sources, and each root skill's metadata. The packaging workflow runs them on every pull request.
+
+### Codex Smoke Test
+
+With Codex CLI installed, verify the complete local marketplace install:
+
+```bash
+npm run test:codex
+```
+
+The script uses a temporary Codex home, runs outside the repository, installs the root plugin, compares every installed skill and reference file with `skills/`, and verifies that Codex discovers the skills from the installed cache. It removes its temporary files on completion. This tests packaging and discovery without an Orca account or model call; it does not exercise the Orca MCP workflows.
+
+### Claude Smoke Test
+
+After installing the marketplace in Claude Code, run `claude mcp list` to check the Orca MCP connection, then try `/orca-alert-triage` with an alert from your environment.
+
+The separate `security-engineer` tests and development setup are documented in [its README](plugins/security-engineer/README.md#developing).
+
 ## Contributing
 
 We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

README.md

@@ -3,6 +3,10 @@
   "version": "2.0.0",
   "type": "module",
   "description": "Skills and plugins to accelerate security workflows with the Orca Cloud Platform",
+  "scripts": {
+    "test": "node scripts/validate-packaging.mjs && node --test scripts/validate-packaging.test.mjs",
+    "test:codex": "node scripts/smoke-test-codex.mjs"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/orcasecurity/orca-skills.git"
@@ -14,6 +18,11 @@
     "alerts",
     "soc",
     "claude",
+    "codex",
+    "cursor",
+    "mcp",
+    "cloud-security",
+    "compliance",
     "skills"
   ],
   "author": "Orca Security",