SuperAPI AI Directory

conventions-claude

Coding & development

View repository

Updated 10-16 07:18

About this skill

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.

Primary authoritative sources:


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:

{
  "name": "my-plugin",
  "version": "0.2.1",
  "description": "Does useful things",
  "author": { "name": "dev" },
  "license": "MIT",
  "keywords": ["tools", "productivity"],
  "commands": "commands/",
  "agents": "agents/",
  "skills": "skills/"
}

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 !cmd`` blocks
  • 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 relative path: commands/shared/name.md
  • Define expected output format explicitly in the body

2.3 Dynamic context injection

  • !`git diff HEAD` — runs command before Claude sees the skill; replaces line with output.
  • ```! fenced blocks — multi-line commands.
  • Disabled if "disableSkillShellExecution": true in settings.

2.4 String substitutions (valid in command/skill bodies)

$ARGUMENTS, $ARGUMENTS[N], $N (positional), $name (named argument), ${CLAUDE_SESSION_ID}, ${CLAUDE_EFFORT}, ${CLAUDE_SKILL_DIR}, ${CLAUDE_PLUGIN_ROOT}. Do NOT flag these as undefined variables.


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. Two or more <example> blocks with diverse scenarios is the minimum for reliable triggering.


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).


6. Rules

Rules live in .claude/rules/<name>.md.

Frontmatter:

  • description — string (required)
  • paths — string array (optional); glob patterns scoping which files this rule applies to

Body format:

  • Lead with a bold imperative: **Always do X.** or **Use Y instead of Z.**
  • Follow immediately with rationale
  • Be specific and testable
  • State what to DO, not only what to avoid (Pink Elephant effect)

Budget: Under 500 lines total per rules file.

Naming convention for ordered sets: NN-kebab-name.md (e.g. 01-formatting.md).


7. Hook Events (Claude Code)

Hook events are case-sensitive. Using wrong case silently ignores the hook.

Confirmed against 2026-06-07 docs refresh (hooks.md):

Event Trigger Context fields
SessionStart Session begin source (startup/resume/clear/compact), model
SessionEnd Session end (trigger only)
UserPromptSubmit User submits a prompt prompt text
PreToolUse Before any tool call tool_name, tool_input
PostToolUse After tool call tool_name, tool_input, tool_output
PermissionRequest When Claude requests permission tool_name, tool_input, permission_mode
Stop Once per turn reason (can set decision: block to prevent stopping)
StopFailure Once per turn — Claude failed to complete reason
FileChanged Per file change filename, watcher_path

Beyond the table above, many more events are valid (SubagentStop, PreCompact, Notification, PostToolUseFailure, Setup, SubagentStart, PermissionDenied, PostCompact, TaskCompleted, MessageDisplay, …). Full allow-list → reference.md. Any documented event name is valid even if it post-dates this doc; do NOT flag as unknown — verify against hooks.md rather than penalizing.

Hook types (canonical, all lowercase in JSON):

  • command — shell script (stdin/stdout)
  • http — HTTP POST endpoint
  • mcp_tool — MCP server tool invocation
  • prompt — LLM evaluation
  • agent — subagent verification

A command hook may add "shell": "powershell" to run that hook in PowerShell instead of the default shell.

Matcher patterns: string (exact), pipe-separated list (Bash|Edit), or regex (non-alphanumeric chars).

MCP tool naming: mcp__<server>__<tool> (e.g., mcp__memory__write.*). Hook matchers use this format.

Exit codes (command hooks):

  • 0 — success (stdout to debug log; for UserPromptSubmit, UserPromptExpansion, and SessionStart, stdout is injected as context)
  • 2 — blocking error (action denied, stderr fed to Claude) — only on blockable events. Non-blockable events ignore exit 2: PostToolUse, PostToolUseFailure, Notification, SessionStart, SessionEnd, InstructionsLoaded, StopFailure, MessageDisplay, SubagentStart, Setup, CwdChanged, FileChanged, PostCompact, WorktreeRemove, PermissionDenied (on PermissionDenied, use JSON retry: true rather than exit 2).
  • 1, 3+ — non-blocking error (logged in debug only)

8. hooks.json Format

Located at .claude/hooks.json or <plugin>/hooks/hooks.json.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/pre-write-check.sh"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are now in strict TDD mode."
          }
        ]
      }
    ]
  }
}

Structure rules:

  • Top-level key: "hooks"
  • Second-level keys: event names (case-sensitive)
  • Each event maps to an array of matcher objects: { "matcher": "<regex>", "hooks": [...] }
  • Each hook object: { "type": "command"|"http"|"mcp_tool"|"prompt"|"agent", "<type-field>": "..." }
  • Field name matches the type: "command" for type command, "prompt" for type prompt, etc.

Optional hook-object fields (current — do NOT flag as malformed): if (Bash-pattern, permission-scoped condition), timeout (seconds), statusMessage, once (v2.1+; skills/agents only), exec-form args (array, as an alternative to shell-form command), and async / asyncRewake for background command hooks.


9. .mcp.json

Claude Code reads MCP server registrations from a standalone JSON file at the repo root (NOT embedded in settings.json like Gemini, NOT inside config.toml like Codex).

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "node",
      "args": ["./server.js"]
    }
  }
}

Plugin scope: <plugin>/.mcp.json at the plugin root, or inline in plugin.json under mcpServers. (Only the plugin-root form is documented; the older .claude-plugin/.mcp.json variant is not.)


10. CLAUDE.md (memory file)

Four memory scopes load in order (managed policy → user → project → local):

Scope Path Notes
Managed policy OS-specific managed path (e.g. /Library/Application Support/ClaudeCode/CLAUDE.md) org-wide, set by administrators
User ~/.claude/CLAUDE.md personal, applies to all projects
Project ./CLAUDE.md or ./.claude/CLAUDE.md shared, committed
Local ./CLAUDE.local.md gitignored personal overrides for this repo

Auto-memory is a separate system at ~/.claude/projects/<slug>/memory/ (see §15) — there is no .claude/memory/*.md convention.

Recommended pattern for multi-tool projects (per analysis/multi-tool-design-2026-05.md decision #5): use a one-line CLAUDE.md that imports AGENTS.md:

@AGENTS.md

This makes AGENTS.md the canonical universal memory file. AGENTS.md is what Codex reads natively; Gemini/Antigravity can be configured to read it via context.fileName array. This is how nlpm itself works.

Body conventions when content lives in CLAUDE.md directly:

  • Build/run instructions
  • Test commands
  • Architecture overview (what lives where)
  • Prerequisites section
  • Valid @-imports must reference existing files

11. .claude/settings.json and .claude/settings.local.json

Field Purpose
permissions Permission policy (allow/deny rules, modes); incl. permissions.additionalDirectories
hooks Hook event registrations (alternative to hooks/hooks.json for project-scoped hooks)
model Default model selection
disableSkillShellExecution If true, disables !...`` and ```! dynamic blocks in skills
env Environment variables injected into the session
statusLine Custom status line command/config
agent Default agent (also the only default-settings key, besides subagentStatusLine, a plugin may set)
effortLevel Default effort
language, outputStyle Locale / output style defaults
enabledPlugins Plugins enabled for the project
claudeMd, claudeMdExcludes Extra memory file globs / exclusions. claudeMd is honored only in managed/policy settings — it has no effect in user/project/local settings.
skillOverrides Per-skill visibility from settings (keys = skill name; values on / name-only / user-invocable-only / off); overrides the skill's own frontmatter
pluginConfigs Stores non-sensitive plugin userConfig values under pluginConfigs[<plugin-id>].options
autoMemoryEnabled, autoMemoryDirectory Auto-memory toggle + location (see §15)
sandbox.enabled Sandbox execution toggle
extraKnownMarketplaces, strictKnownMarketplaces Marketplace trust config

theme is not a documented settings.json field — do not flag its absence or treat it as valid here (removed from this list 2026-06-07). The above is representative, not exhaustive; treat unrecognized-but-plausible keys as advisory, not errors.

Rule: .local.json is gitignored (per-user); the non-local file is shared. NEVER set bypassPermissions: true in the shared file.


12. LSP Servers (.lsp.json)

Stable in 2026 (was experimental in 2025). .lsp.json file, or a lspServers object in plugin.json. Required fields command + extensionToLanguage. Full per-server schema → reference.md.


13. Monitors (monitors/monitors.json)

Experimental — lives under experimental.monitors (§1); its manifest schema may change between releases while it stabilizes. Plugin background watchers; requires v2.1.105+. Per-entry required name + command + description. Full schema → reference.md.


14. Reference Syntax

Commands referencing shared partials:

<!-- Include: commands/shared/discover.md -->

Or by instruction: "Follow the steps in commands/shared/discover.md"

Agents referencing skills in frontmatter:

skills: ["nlpm:conventions", "nlpm:conventions-claude"]

Hooks referencing scripts:

"command": "${CLAUDE_PLUGIN_ROOT}/scripts/check.sh"

Always use ${CLAUDE_PLUGIN_ROOT} for intra-plugin file references. Hardcoded absolute paths break portability.

Cross-plugin skill references use the same plugin:skill format. The plugin must be installed for the reference to resolve.


15. Memory File Conventions (~/.claude/projects/<slug>/memory/)

Claude Code writes per-project persistent memory at ~/.claude/projects/<project-slug>/memory/ ("Auto memory", v2.1.59+). Toggled by autoMemoryEnabled; location overridable via autoMemoryDirectory (§11). At session start the first ~200 lines / 25 KB of MEMORY.md plus topic files are loaded into context.

Index file: MEMORY.md (no frontmatter; one-line-per-entry index).

Individual memory files MUST include YAML frontmatter:

---
name: "short identifier"
description: "one-line summary"
type: user | feedback | project | reference
---

type values:

Value Meaning
user Preferences, habits, or facts about the user
feedback Corrections or lessons from past sessions
project Project-specific facts, decisions, or context
reference External reference material copied into memory

Rules:

  • Every memory file must appear in MEMORY.md (orphans are flagged).
  • MEMORY.md itself is the index; not scored as a memory file.
  • Memory files should not reference removed files or functions.

16. Claude Code Tool Catalog

Tool names valid in tools:, allowed-tools:, disallowed-tools:. Never flag a well-formed tool name as "unknown" or "undocumented" — the catalog grows and any string matching Pascal-name or mcp__<server>__<tool> patterns is valid. Key renames: Task → Agent (alias kept); MultiEdit, BashOutput, KillBash removed; TodoWrite default-off (→ Task* family); SlashCommand folded into Skill.

Full catalog — built-in tools, renames/removals, MCP naming → reference.md. Authoritative source: code.claude.com/docs/en/tools-reference.md.


17. Plugin distribution

Marketplace manifest: .claude-plugin/marketplace.json at the marketplace repo root. Required top-level: name, owner (maintainer-info object), plugins. Optional: $schema, description, version, metadata.pluginRoot, renames. Per-plugin entries may add category, tags, strict, relevance, defaultEnabled. Full schema, source types, and renames/strict semantics → reference.md.

Plugin from URL (v2.1.x): --plugin-url and --plugin-dir flags accept .zip archives.

Namespacing: plugin skills, commands, and agents are all namespaced under the plugin — /my-plugin:hello for skills/commands, my-plugin:code-reviewer in the @-mention typeahead for agents. Prevents conflicts.


18. Scope and uncertainty

This skill covers Claude Code conventions. It does NOT cover:

  • Universal SKILL.md spec → nlpm:conventions
  • Penalty tables → nlpm:scoring

Resolved in the 2026-08-02 refresh (no longer uncertain):

  • Hook event lists verified 30/30 against current hooks.md (§7); exit-code non-blocking list completed.
  • description is Recommended, not Required (§2.1); fable model alias + claude-opus-5 example added (§2.1, §4).
  • Memory scopes corrected to managed/user/project/local; the bogus .claude/memory/*.md claim removed (§10, was self-contradictory with §15).
  • Monitors reclassified experimental (§13); LSP confirmed genuinely stable (§12).
  • marketplace.json required owner + strict/renames folded into §17; namespacing corrected (agents/commands are namespaced too). slash-commands.md citation retired for skills.md/commands.md.
  • Version gates v2.1.142 (TodoWrite default-off) and v2.1.154 (defaultEnabled) confirmed literal in current docs.

Still approximate (verify before citing a specific tag):

  • Exact version pins beyond v2.1.218 (highest gate observed); no single current top-level Claude Code version is stated in the docs.
  • Whether a language settings.json key still exists — not found in repeated fetches, but the source page returned inconsistent partial coverage, so it is NOT dropped on that evidence alone.
  • Whether .claude/rules/ frontmatter recognizes a description field (§6) — not shown in any current docs example; unverified this pass.