skills.rest
AvaTar-ArTs
AvaTar-ArTsCOMMUNITY
Explore all skills by this author →
GitHub

plugin-structure

Guides creation and organization of Codex plugin directories, manifests, and components.

Updated Jul 10, 2026
Search Tags:#hooks#scaffold#manifest#directory structure#plugin.json#auto-discovery#codex plugin
One-click install
npx skills add https://github.com/AvaTar-ArTs/.Agent-skills --skill plugin-structure-avatar-arts
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: plugin-structure
Source: https://github.com/AvaTar-ArTs/.Agent-skills/tree/main/skills/plugin-structure
Command: npx skills add https://github.com/AvaTar-ArTs/.Agent-skills --skill plugin-structure-avatar-arts

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Developers building Codex plugins often struggle with where to place manifests, commands, agents, skills, and hooks, and how to configure auto-discovery and portable paths. This Skill provides the canonical directory layout, plugin.json configuration rules, and naming conventions so plugins load correctly on the first try. ## Core Features & Use Cases - Standardized Directory Layout: Defines the required .Codex-plugin/plugin.json manifest location and root-level component directories for commands, agents, skills, and hooks. - Manifest Configuration: Documents required and recommended plugin.json fields, custom component paths, semantic versioning, and kebab-case naming rules. - Portable Path References: Explains how to use ${CLAUDE_PLUGIN_ROOT} in hooks, MCP server definitions, and scripts so plugins work across operating systems and install methods. - Use Case: When scaffolding a new plugin with a slash command, a subagent, and a PreToolUse hook, follow this Skill to place each file correctly, write the manifest, and reference hook scripts portably. ## Quick Start Ask the AI to scaffold a new Codex plugin named code-review-assistant with one command, one agent, and a hook, following the standard plugin structure.

Frequently Asked Questions about plugin-structure

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a Codex plugin with the correct directory structure?▼

Create a plugin root containing a .Codex-plugin directory with plugin.json, then add root-level directories for the components you use: commands/, agents/, skills/, and hooks/. Only the name field is required in the manifest, and all component directories must sit at plugin root, not inside .Codex-plugin.

Where should the plugin.json manifest file be located?▼

The plugin.json manifest must be placed inside a .Codex-plugin directory at the plugin root. Component directories like commands and agents stay at the plugin root level, never nested inside .Codex-plugin.

How do I reference plugin files portably across operating systems?▼

Use the ${CLAUDE_PLUGIN_ROOT} environment variable for all intra-plugin paths in hook commands, MCP server arguments, and scripts. Never hardcode absolute paths or home directory shortcuts, since install locations vary by user and platform.

Why is my Codex plugin component not loading or auto-discovered?▼

Components fail to load when files are in the wrong directory, lack correct extensions, or have invalid YAML frontmatter. Verify skills contain a SKILL.md file, directories sit at plugin root, and the plugin is enabled, then restart Codex to reload configuration.

Can I use custom paths for commands and agents in plugin.json?▼

Yes, plugin.json supports custom path fields for commands, agents, hooks, and mcpServers. Paths must be relative to the plugin root, start with ./, and they supplement rather than replace the default auto-discovered directories.

Related Skills

Explore More Software Engineering Skills→
thevibeworksthevibeworks
28

plugin-structure

Define Claude Code plugin directory layout, manifest configuration, and component discovery rules.

Official
Intermediate
outfitter-devoutfitter-dev
28

claude-plugin-distribution

Package and distribute Claude Code plugins with versioning and GitHub releases.

Official
Intermediate
overtimepogovertimepog

ghcc-doctor

Diagnose greyhatcc plugin installation, configuration, dependency, and MCP server health issues.

Community
Intermediate
AreteDriverAreteDriver
4

plugin-builder

Build and package Claude Code plugins with a plugin.json manifest.

Community
Advanced