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 /codex-toolkit:refresh-knowledge to update from latest docs.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
claude-code-conventions
description
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 /codex-toolkit:refresh-knowledge to update from latest docs.
version
0.2.0
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 /codex-toolkit:refresh-knowledge to refresh.
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
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 many 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.
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):
