/conventions-claude

name: conventions-claude
description: "Claude Code artifact schemas: plugin.json, frontmatter, hooks, settings, tools."
version: 0.3.1
user-invocable: false

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](reference.md#pluginjson-example).**

---

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 n