# Claude Code Conventions

> Canonical reference for Claude Code plugin artifact schemas, hook events, frontmatter fields, and naming conventions. Used to inject domain knowledge into Codex audit prompts. Run /cc-suite:refresh-knowledge to update from latest docs.

- Skill: `xiaolai/claude-code-conventions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xiaolai/claude-code-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiaolai/claude-code-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: xiaolai (https://skillmd.com/u/xiaolai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xiaolai/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`). Run `/cc-suite:refresh-knowledge` to refresh.

## 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>