Conventions Claude

Claude Code Conventions

Tool-specific overlay for Claude Code plugin artifacts. Loaded by the scorer and checker when an artifact is classified as Tier 2-Claude (per agents/scorer.md step 3). The universal floor lives in nlpm:conventions; this overlay adds Claude-Code-specific schemas on top.

Last refreshed: 2026-08-02 against current docs (Claude Code ≥ v2.1.218); §2.2, §2.4 and §14 corrected 2026-10-01 against Claude Code 2.1.285. Notation: a + splits $+ARGUMENTS and the dollar-brace variables such as $+{CLAUDE_PLUGIN_ROOT} throughout this file. The real tokens have no +. They are split because Claude Code replaces the contiguous tokens with their values whenever it loads a skill, including when an agent preloads it, so a literal token here would reach the reader as an empty string or a path (§2.4).

Primary authoritative sources:

• https://code.claude.com/docs/en/claude_code_docs_map.md
• https://code.claude.com/docs/en/skills.md
• https://code.claude.com/docs/en/hooks.md
• https://code.claude.com/docs/en/plugins.md
• https://code.claude.com/docs/en/plugins-reference.md
• https://code.claude.com/docs/en/sub-agents.md
• https://code.claude.com/docs/en/settings.md
• https://code.claude.com/docs/en/memory.md
• https://code.claude.com/docs/en/commands.md — built-in commands + bundled skills (successor to the retired slash-commands.md)
• https://code.claude.com/docs/en/tools-reference.md — authoritative built-in tool catalog (see §16)
• https://code.claude.com/docs/en/plugin-marketplaces.md
• https://code.claude.com/docs/en/workflows.md

1. .claude-plugin/plugin.json

The plugin manifest.

Required fields:

• name — string, kebab-case, unique identifier

The manifest is fully optional — artifacts auto-discover from conventional paths, and only name is required when present. Unrecognized top-level fields are ignored with a warning (error only under claude plugin validate --strict).

Optional fields:

• version — semver string (e.g. "0.1.0"). If omitted, commit SHA is used (every commit = new version). For stable releases, set explicit semver.
• description — one-line summary
• displayName — human-readable name shown in installer UI (v2.1.143+)
• author — object: { "name": "...", "email": "...", "url": "..." }
• homepage — URL string
• repository — URL string (the docs' Metadata table types this strictly as string; no object form is documented)
• license — SPDX identifier
• keywords — string array for discovery
• $schema — URL to the manifest JSON Schema (editor validation)
• defaultEnabled — boolean; whether the plugin is enabled on install (v2.1.154+)
• userConfig — object; per-key prompts shown to the user at enable time; values exposed as $+{user_config.<key>} substitutions
• channels — array; message-injection channel bindings
• dependencies — array of other plugins this one requires (supports semver constraints)

NOT plugin.json fields (common mistake):

• agent — this is a settings.json default key (a plugin's bundled settings.json supports only agent and subagentStatusLine), not a manifest field.
• category — belongs to a marketplace.json plugin entry, not the manifest.

Artifact path fields (all optional, string or string[]):

• commands — path(s) to command markdown files
• agents — path(s) to agent markdown files
• skills — path(s) to skill directories
• hooks — path to hooks.json
• mcpServers — path(s) to MCP server config
• lspServers — path(s) to LSP server config (stable in 2026; schema in §12)
• outputStyles — path(s) to output style definitions
• workflows — path(s) to workflow script files/directories (replaces default workflows/; ties to the Workflow tool)
• experimental.themes — path(s) to theme definitions (was top-level themes; now nested under experimental)
• experimental.monitors — path(s) to monitor config (was top-level monitors; schema in §13). Top-level still works but claude plugin validate warns; a future release will require the experimental.* form.

Plugin structure note: a bin/ directory in a plugin root puts its executables on the Bash tool's PATH — files there are invokable as bare commands in any Bash call while the plugin is enabled.

Example manifest → reference.md.

2. Commands and Skills — merged surfaces (v2.1.x change)

Critical: as of Claude Code v2.1.x, commands and skills are the same architecture. Both surfaces support the same frontmatter and execution semantics. The recommended canonical path is:

.claude/skills/<name>/SKILL.md     # preferred for new development
.claude/commands/<name>.md         # still works; equivalent behavior

Existing .claude/commands/ files continue to function. New code should prefer the skill layout because it allows companion files (scripts/, references/, examples/) in the same directory.

Authoritative reference: https://code.claude.com/docs/en/skills.md (command/skill frontmatter now lives here; the old slash-commands.md page was retired)

2.1 Frontmatter (shared between commands and skills)

Recommended (per official docs, the only recommended frontmatter field — all keys are technically optional):

• description — string; explains what it does and when to invoke. Combined with when_to_use: if present. The schema treats it as optional, but a model-invoked skill with no (or a weak) description cannot trigger reliably — so nlpm scores a missing/weak description as a quality finding (R04), not a hard schema violation.

Optional (universal):

• name — string; per official docs, explicitly optional. When omitted, filename or enclosing directory is used. Pre-v0.7.15 nlpm incorrectly flagged missing name: as a bug; corrected after Jeffallan/claude-skills#184 maintainer feedback.
• argument-hint — string; placeholder shown in UI (e.g., "[path]")
• arguments — space-separated or YAML list of named arguments for $name substitution (e.g., "issue branch")
• allowed-tools — string array OR space-separated string; pre-approved tools (no per-use prompt). Format: "Read Grep Bash(git *)" or ["Read", "Grep"].
• disallowed-tools — string array OR space-separated string; tools removed from the pool while the skill is active.
• model — haiku / sonnet / opus / fable / a full model ID / inherit (keep the active model); overrides session model for one turn.
• effort — low / medium / high / xhigh / max; overrides session effort.
• user-invocable — boolean; false hides from menu (only Claude invokes).
• disable-model-invocation — boolean; true means only the user invokes (manual /skill-name only).

Optional (v2.1.x additions — NEW since pre-2026 conventions):

• when_to_use — string; additional trigger hints (appends to description)
• context — "fork" runs in a forked subagent (isolates from main history)
• agent — which subagent type (built-in: Explore, Plan, general-purpose)
• hooks — {...} skill-scoped hooks (same shape as settings.json hooks)
• paths — glob patterns; auto-load only for matching files (e.g., "src/**/*.ts,lib/**/*.ts")
• shell — bash (default) or powershell for the dynamic context blocks in §2.3
• background — boolean; only meaningful with context: fork. false waits for the forked subagent's result in the invoking turn instead of backgrounding it (default true; v2.1.218+).

Boolean frontmatter fields accept yes/no/on/off/1/0 (any case) in addition to true/false (v2.1.218+). The combined description + when_to_use shown in the skill listing is truncated at 1,536 characters — keep triggers within that budget.

2.2 Body conventions

• Write imperative instructions directed at Claude (not the user)
• Use numbered steps for multi-phase workflows
• Reference shared partials by plugin-root path, not a bare relative path (§14)
• Define expected output format explicitly in the body

2.3 Dynamic context injection

• Inline form: an exclamation mark placed directly before a single-backtick code span holding a command (e.g. git diff HEAD) — runs the command before Claude sees the skill and replaces the span with its output.
• Fenced form: a code fence whose opening three backticks are followed directly by an exclamation mark — runs its multi-line commands the same way. Both forms are described in words here because Claude Code would execute them when this skill is preloaded.
• Disabled if "disableSkillShellExecution": true in settings.

2.4 String substitutions (valid in command/skill bodies)

Claude Code replaces these tokens in command and skill bodies. Do NOT flag them as undefined variables. Each is written with this file's + split (see Notation at the top); drop the + to get the real token.

Preloading substitutes too (observed on Claude Code 2.1.285, 2026-10-01): when an agent preloads a skill through skills:, $+ARGUMENTS becomes an empty string and every $+{CLAUDE_…} token above becomes its value; $+N and $+name stay literal because a preload passes no arguments. A backslash protects $+ARGUMENTS but not the braced tokens. A reference skill that describes these tokens must therefore split them as this file does, or its reader sees the substituted values instead of the token names.

3. Shared Partials

Reusable shared partials located in commands/shared/.

Rules:

• MUST include user-invocable: false in frontmatter — prevents appearing as top-level commands
• MUST have a description stating their purpose as a partial
• Referenced by full relative path from the consuming command file
• Can contain any mix of instructions, templates, or decision logic

4. Agent Frontmatter

Agents live in .claude/agents/<name>.md.

The system prompt is the markdown body of the file (in --agents JSON form it is the prompt key). There is no system-prompt frontmatter key — flagging or recommending one is a bug (corrected 2026-06-07 against sub-agents.md).

Documented fields:

• name — string; identifier for invocation. Cannot contain : (reserved for plugin-scoped identifiers, v2.1.218+).
• description — string; critical for reliable triggering — should contain 3+ specific phrases describing when to use this agent
• tools — tools the agent body uses; two valid formats:
  • JSON array: tools: ["Read", "Glob"]
  • Comma-separated string: tools: Read, Glob, Grep
• disallowedTools — tools removed from the inherited pool (this is the correct key — there is no tool-restrictions: {allow, deny} key; the old nlpm name was wrong)
• model — haiku / sonnet / opus / fable / a full ID (e.g. claude-opus-5) / inherit; defaults to inherit
• skills — preload skill content into this agent's context at startup. Two valid formats:
  • JSON array: skills: ["nlpm:conventions"]
  • YAML list: skills:\n - nlpm:conventions

Convention / additional fields:

• effort — low / medium / high / xhigh / max
• color — one of red, blue, green, yellow, purple, orange, pink, cyan; visual label. magenta is NOT valid (old nlpm list had it; the current valid set adds purple, orange, pink).
• permissionMode — default (alias manual, v2.1.200+) / acceptEdits / auto / dontAsk / bypassPermissions / plan
• isolation — only valid value "worktree" (runs the agent in a git worktree)
• memory — user / project / local
• maxTurns — integer turn cap
• background — boolean; run asynchronously
• initialPrompt — string; seeds the agent's first turn
• mcpServers, hooks — agent-scoped overrides

Plugin-shipped agents are restricted: hooks, mcpServers, and permissionMode are ignored for agents distributed inside a plugin (security). Score plugin agents accordingly.

Best practice: include <example> blocks in description. The description is placed in the Agent tool's text on every turn and is the only thing Claude sees when choosing an agent, so examples belong there (not in the body). One well-chosen <example> plus a "Not for …" sentence carries the routing signal; extra examples are allowed but cost always-on context. nlpm R09 deducts 5 points when the description exceeds 1,200 characters.

5. Skills — Claude Code path conventions

Universal SKILL.md spec lives in nlpm:conventions (open spec at agentskills.io). Claude Code uses these path conventions:

• Single plugin skill: skills/<name>/SKILL.md
• Multi-skill plugin: skills/<plugin>/<name>/SKILL.md
• Project-scoped: .claude/skills/<name>/SKILL.md
• User-scoped: ~/.claude/skills/<name>/SKILL.md

Skill discovery paths now support parent-directory and monorepo nested scanning (v2.1.x). Skills from ./parent/.claude/skills/ and ./packages/frontend/.claude/skills/ auto-load. Skills from --add-dir paths also load from .claude/skills/ within added directories.

Supporting files: Same directory as SKILL.md — scripts/, references/, examples/, etc. Reference them from SKILL.md so Claude knows when to load them.

Skill preloading in agents (v2.1.x): Declare skills: [name1, name2] in agent frontmatter to inject full skill content at startup (vs. Claude auto-loading on demand).