<!-- Generated by scripts/generate-site-content.py — do not edit by hand -->


# codex-plugin-structure

Only plugin.json belongs in .codex-plugin/

| | |
|---|---|
| **Severity** | warning (auto) |
| **Autofix** | - |
| **Since** | v0.18.0 |
| **Repo Types** | codex-marketplace, codex-plugin |
| **Category** | [OpenAI Codex](codex.md) |

## Why

The Codex specification reserves `.codex-plugin/` for the manifest alone:
"Only `plugin.json` belongs in `.codex-plugin/`. Keep `skills/`,
`hooks/`, `assets/`, `.mcp.json`, and `.app.json` at the plugin root."
Files parked in the manifest directory are not discovered where Codex
looks for them, so hooks and assets stored there never load.

## Examples

**Bad:**

```text
my-plugin/
├── .codex-plugin/
│   ├── plugin.json
│   └── hooks.json      # never discovered
└── README.md
```

**Good:**

```text
my-plugin/
├── .codex-plugin/
│   └── plugin.json
├── hooks/
│   └── hooks.json
└── README.md
```

## How to fix

Move the reported file to the plugin root — `hooks/hooks.json` for
lifecycle hooks, `.mcp.json` for bundled MCP servers, `.app.json` for
registered MCP mappings, and `assets/` for icons and screenshots — then
point the matching `plugin.json` field at its new location.

## Configuration

```yaml
rules:
  codex-plugin-structure:
    enabled: auto  # true | false | auto
    severity: warning
```


*Run `skillsaw explain codex-plugin-structure` to see this documentation and the rule's effective configuration in your terminal.*