claude-code-conventions

# Claude Code Plugin Conventions Reference > **Purpose**: This skill is the single source of truth for Claude Code artifact conventions. Audit commands inject this content into Codex's `developer-instructions` so Codex can accurately validate Claude Code artifacts despite having no native knowledge of the platform. > > **Freshness**: Last updated 2026-03-25 from context7 (`/websites/code_claude_en_plugins-reference`, `/websites/code_claude_en_plugins`). To refresh it, ask the user to type `/cc-suite:refresh-knowledge` in Claude Code. ## When to Use Load this skill when: - Auditing Claude Code plugin artifacts (commands, agents, skills, hooks, plugin.json) - Validating frontmatter fields against the official schema - Checking hook event names, types, and output formats - Authoring new plugin artifacts and need the canonical field reference - Running `/cc-suite:audit-plugin`, `/cc-suite:audit-command`, `/cc-suite:audit-agent`, or `/cc-suite:audit-skill` ## plugin.json Schema **Only `name` is strictly required.** Version and description are strongly recommended but optional. Required: - `name` (string): plugin identifier, kebab-case. Used for namespacing (e.g., `plugin-dev:agent-creator`) Recommended: - `version` (string): semver `X.Y.Z`. If also set in marketplace entry, plugin.json takes precedence - `description` (string): brief purpose Optional metadata: - `author` (object): `{ "name": "string", "email": "string", "url": "string" }` - `homepage` (string): URL to plugin docs - `repository` (string): URL to source code - `license` (string): SPDX identifier (e.g., `"MIT"`, `"Apache-2.0"`) - `keywords` (string[]): discovery tags Component path fields (string, string[], or inline object): - `commands` — path(s) to command files. Default: `./commands/` (auto-discovered) - `agents` — path(s) to agent files. Default: `./agents/` (auto-discovered) - `skills` — path(s) to skill directories. Default: `./skills/` (auto-discovered) - `hooks` — path to hooks config OR inline hooks object. Default: `./hooks/hooks.json` - `mcpServers` — path to MCP config OR inline object. Default: `./.mcp.json` - `lspServers` — path to LSP config. Default: `./.lsp.json` - `outputStyles` — path to output style definitions If omitted, components are auto-discovered from default locations. ## Command Frontmatter Location: `commands/<name>.md` (auto-discovered from `commands/` directory) Required fields: - `description` (string): shown in `/help`, must be specific and actionable Optional fields: - `argument-hint` (string): usage pattern (e.g., `"<file> [--flag]"`) - `allowed-tools` (string[]): restrict available tools. Omit for all tools - `model` (string): override session model (`haiku`, `sonnet`, `opus`) - `user-invocable` (boolean): `false` for shared partials in `commands/shared/` Body: imperative instructions FOR Claude, not documentation TO user. ## Shared Partial Frontmatter Location: `commands/shared/<name>.md` Required: - `user-invocable: false` Referenced by commands to eliminate boilerplate. Not shown in `/help`. ## Agent Frontmatter Location: `agents/<name>.md` (auto-discovered) Official documented fields: - `name` (string): agent identifier - `description` (string): what the agent does and when to invoke it Widely-used convention fields (not in official docs but used by all xiaolai plugins and numerous community plugins): - `model` (string): `haiku`, `sonnet`, `opus` - `color` (string): UI color hint — `cyan`, `blue`, `magenta`, `yellow`, `green`, `red` - `tools` (string[] or comma-separated): tools available to the agent - `skills` (string[]): skills loaded into context, format `plugin-name:skill-name` - `allowed-tools` (string[]): alternative to `tools` Agents can also embed inline hooks in frontmatter for `PreToolUse`/`PostToolUse` within their scope. Body: system prompt defining mission, instructions, and output format. Best practice: include `<example>` blocks in description showing when/how to trigger. ## Skill Structure Location: `skills/<skill-name>/SKILL.md` (or `skills/<plugin-name>/<skill-name>/SKILL.md`) Required frontmatter: - `name` (string): skill identifier - `description` (string): when/why to use — acts as trigger for auto-loading Optional frontmatter: - `version` (string): semver - `globs` (string or string[]): file patterns that scope this skill Body: reference material. Keep under 500 lines for context efficiency. Supporting files alongside SKILL.md: - `references/` — detailed reference material - `examples/` — working code examples - `scripts/` — utility scripts Skills in `commands/` directory work identically (legacy layout). Both are auto-discovered. ## Hook Events Location: `hooks/hooks.json` (can have multiple files: `hooks.json`, `security-hooks.json`, etc.), inline in `plugin.json` hooks field, or inline in agent frontmatter. Valid event types: - `PreToolUse` — before a tool executes (can block via permission decision) - `PostToolUse` — after a tool executes successfully - `PostToolUseFailure` — after a tool execution fails - `PermissionRequest` — when tool permission is needed - `UserPromptSubmit` — when user sends a message - `Stop` — when Claude stops responding - `SubagentStop` — when a subagent completes - `SessionStart` — when a session begins - `SessionEnd` — when a session ends - `PreCompact` — before context compression - `Notification` — for notifications - `InstructionsLoaded` — after CLAUDE.md files are loaded **Note**: Event names are case-sensitive. Hook types: - `command` — run a shell command, receives JSON on stdin - `prompt` — evaluate a prompt with the LLM - `agent` — spawn an agentic verifier for complex verification tasks Hook output (for `command` type blocking decisions): ```json { "hookSpecificOutput": { "permissionDecision": "allow" | "deny", "permissionDecisionReason": "explanation" } } ``` Matcher: regex pattern for tool name (e.g., `"Bash"`, `"Write|Edit"`, `"mcp__.*"`) ## hooks.json Format ```json { "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh" } ] } ] } } ``` Multiple hook config files are supported in the `hooks/` directory. ## .mcp.json Format ```json { "mcpServers": { "server-name": { "command": "executable", "args": ["arg1", "arg2"], "cwd": "${CLAUDE_PLUGIN_ROOT}", "env": { "KEY": "value" } } } } ``` ## marketplace.json Format Per-plugin marketplace (for `claude plugin marketplace add`): ```json { "name": "marketplace-name", "owner": { "name": "author-name" }, "plugins": [ { "name": "plugin-name", "source": { "source": "github", "repo": "owner/repo" }, "description": "...", "version": "X.Y.Z", "author": { "name": "..." }, "category": "developer-tools" } ] } ``` `owner` with `name` is required for marketplace validation. Source types: `github`, `git`, `url`, `npm`, `file`, `directory`, `hostPattern` ## Plugin Directory Layout ``` plugin-name/ ├── .claude-plugin/ │ ├── plugin.json # manifest (name required, rest optional) │ └── marketplace.json # optional ├── commands/ # auto-discovered │ ├── command-name.md │ └── shared/ # non-invocable partials │ └── partial-name.md ├── agents/ # auto-discovered │ └── agent-name.md ├── skills/ # auto-discovered │ └── skill-name/ │ ├── SKILL.md │ ├── references/ # optional │ ├── examples/ # optional │ └── scripts/ # optional ├── hooks/ # can have multiple .json files │ ├── hooks.json │ └── security-hooks.json # additional hook configs ├── scripts/ # utility scripts ├── settings.json # default plugin settings (optional) ├── .mcp.json # optional MCP servers ├── .lsp.json # optional LSP servers ├── CLAUDE.md # project instructions ├── README.md └── LICENSE ``` `${CLAUDE_PLUGIN_ROOT}` resolves to the plugin's root directory at runtime. Use it in all script paths for portability. ## Naming Conventions - Plugin names: kebab-case (`reading-assistant`, `codex-toolkit`) - Command files: kebab-case `.md` (`audit-plugin.md`) - Agent files: kebab-case `.md` (`qc-coordinator.md`) - Skill directories: `skill-name/SKILL.md` or `plugin-name/skill-name/SKILL.md` - Script files: kebab-case with extension (`codex-preflight.sh`, `parse_epub.py`) ## Settings - `settings.json` at plugin root — default settings shipped with the plugin - `~/.claude/settings.json` — global user settings - `{project}/.claude/settings.json` — project settings (committed) - `{project}/.claude/settings.local.json` — local settings (gitignored) - `.claude/<plugin-name>.local.md` — per-plugin config with YAML frontmatter ## CLAUDE.md - Project-level instructions for Claude Code - Supports `@` import syntax to reference other files - Loaded from: project root, `.claude/`, `~/.claude/`, parent directories - Priority: closer to project root wins - `claudeMdExcludes` setting can ignore specific CLAUDE.md files ## Quality Standards ### Commands - Description: specific and actionable - Steps: numbered, unambiguous, all paths covered - Tools: match `allowed-tools`, least-privilege - Output: format defined (report template) - Errors: fallback paths specified ### Agents - Description: include `<example>` blocks for triggering - Model: match task complexity (haiku mechanical, sonnet reasoning, opus judgment) - Tools: least-privilege - Body: mission, instructions, output format ### Skills - Description: trigger phrases matching user queries - Body: under 500 lines, patterns over theory - Code examples: runnable, not pseudocode - Scope: clear boundaries, cross-references to related skills ### Rules (.claude/rules/) - YAML frontmatter: `description` (required), `paths` (optional glob array) - Budget: <500 lines total across all rule files - Format: bold imperative + rationale + positive framing - Enforceable: testable, specific, observable - No duplication of linter/formatter/CI enforcement ## Scope Note Covers Claude Code's own artifact schemas and naming conventions, and exists to inject that reference material into Codex audit prompts. For running an audit against those conventions, use `$audit` or `$audit-fix`. For authoring cc-suite advisor agents — a different, cc-suite-specific file format — use `agent-design`. For choosing canonical terminology inside cc-suite artifacts, use `vocabulary`. ## Example Invocations <example> Context: An audit needs to judge whether a hook event name in a plugin is valid. user: "Is `pretooluse` a real Claude Code hook event?" assistant: "I'll check claude-code-conventions, which lists the confirmed event names and their casing — the valid form is `PreToolUse`, so this hook would never fire." </example> <example> Context: The user is authoring a new command file and is unsure which frontmatter fields are mandatory. user: "What does a command file actually need in its frontmatter?" assistant: "I'll load claude-code-conventions for the command frontmatter section — only `description` is required; `argument-hint`, `allowed-tools`, and `model` are optional." </example>