Claude Code Plugin Conventions

Canonical reference for all NL programming artifact schemas, frontmatter fields, hook events, and naming conventions. Use this skill when linting, writing, or reviewing any Claude Code plugin component.

---

1. plugin.json

The plugin manifest. Located at .claude-plugin/plugin.json.

Required fields:

• name — string, kebab-case, unique identifier

Optional fields:

• version — semver string (e.g. "0.1.0")
• description — one-line summary of what the plugin does
• author — object: { "name": "...", "email": "...", "url": "..." }
• homepage — URL string
• repository — URL string or object
• license — SPDX identifier (e.g. "MIT")
• keywords — string array for discovery

Component 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
• outputStyles — path(s) to output style definitions

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. Command Frontmatter

Commands live in commands/*.md. Frontmatter is YAML between --- delimiters.

Required fields:

• description — string; explains what the command does and when to invoke it

Optional fields:

• argument-hint — string; shown in UI as placeholder (e.g. "[path]", "<file>")
• allowed-tools — string array; tools Claude may call while executing this command
• model — one of haiku, sonnet, opus; selects model tier
• user-invocable — boolean; set false for shared partials that should not appear in menus

Body convention:

• 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 the expected output format explicitly in the body

Example:

---
description: "Lint all NL artifacts in the current project and report quality scores"
argument-hint: "[path]"
allowed-tools: ["Read", "Glob"]
model: sonnet
---

---

3. Shared Partials

Reusable command fragments. Located in commands/shared/.

Rules:

• MUST include user-invocable: false in frontmatter — prevents them appearing as top-level commands
• MUST have a clear 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

Example frontmatter:

---
description: "Shared: discover NL artifact files in a directory tree"
user-invocable: false
allowed-tools: ["Glob"]
---

---

4. Agent Frontmatter

Agents live in agents/*.md. They are specialized Claude instances invoked by commands or other agents.

Documented fields:

• name — string; identifier used when referencing or invoking this agent
• description — string; critical for reliable triggering — should contain 3+ specific phrases describing when to use this agent

Convention fields (not enforced by schema but strongly recommended):

• model — haiku / sonnet / opus; declare explicitly
• color — one of cyan, blue, magenta, yellow, green, red; visual label in UI
• tools — tools the agent body actually needs; two valid formats (both accepted by Claude Code):
  • JSON array: tools: ["Read", "Glob"]
  • Comma-separated string: tools: Read, Glob, Grep
• skills — skill references; two valid formats:
  • JSON array: skills: ["nlpm:conventions"]
  • YAML list: skills:\n - nlpm:conventions

Best practice: include <example> blocks in description:

---
description: |
  Scans a directory for Claude Code artifact files. Use this agent when
  you need to discover commands, agents, skills, rules, or hooks. Also
  triggers on "inventory NL files" or "find plugin components".

  <example>
  Context: User asks to audit a plugin repo
  user: find all the agent files in this plugin
  assistant: I'll scan the directory structure for agent markdown files...
  </example>

  <example>
  Context: Command invokes scanner as sub-agent
  user: /scan
  assistant: Invoking scanner agent to discover NL artifacts...
  </example>
model: haiku
color: cyan
tools: ["Glob", "Read"]
skills: ["nlpm:conventions"]
---

Two or more <example> blocks with diverse scenarios is the minimum for reliable triggering.

---

5. Skill Structure

Skills provide reference knowledge to agents and commands.

Path conventions:

• Single plugin skill: skills/<name>/SKILL.md
• Multi-skill plugin: skills/<plugin>/<name>/SKILL.md

Frontmatter:

• name — string (required)
• description — string (required); used for discovery and triggering
• version — semver string (optional)
• globs — string array (optional); file patterns this skill applies to

Body rules:

• Under 500 lines — exceeding this creates context bloat
• Reference material only — no imperative instructions (those belong in commands/agents)
• Include a scope note: what this skill covers and what it does NOT cover
• Cross-reference related skills with their plugin:skill identifiers

Supporting directories (optional):

• references/ — external docs, specifications, examples
• examples/ — concrete worked examples
• scripts/ — helper scripts referenced by hooks or commands

---

6. Rules

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

Frontmatter:

• description — string (required); summary shown in rule lists
• 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: "Because W, using X ensures..."
• Be specific and testable — vague rules cannot be linted or enforced
• State what to DO, not only what to avoid (Pink Elephant effect: prohibitions without alternatives are ignored)

Budget: Under 500 lines total per rules file.

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

Example:

---
description: "Always use kebab-case for file and plugin names"
paths: ["**/*.json", "**/*.md"]
---

**Use kebab-case for all file and plugin names.**

Because Claude Code resolves plugin references by exact string match, inconsistent casing
causes lookup failures. `my-plugin` and `MyPlugin` are treated as different identifiers.

Correct: `my-plugin`, `tdd-guardian`, `echo-sleuth`
Incorrect: `myPlugin`, `MyPlugin`, `my_plugin`

---

7. Hook Events

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

Available events:

Event	Trigger
PreToolUse	Before any tool call
PostToolUse	After successful tool call
PostToolUseFailure	After failed tool call
PermissionRequest	When Claude requests permission
UserPromptSubmit	When user submits a prompt
Stop	When main agent stops
SubagentStop	When sub-agent stops
SessionStart	Session initialization
SessionEnd	Session teardown
PreCompact	Before context compaction
Notification	On notification events
InstructionsLoaded	After instructions load

Hook types: command, prompt, agent

Matcher: Regex pattern matched against the tool name (for tool hooks). Empty string matches all.

Permission decision output (for PermissionRequest hooks):

{
  "hookSpecificOutput": {
    "permissionDecision": "allow",
    "permissionDecisionReason": "This tool call is safe because..."
  }
}

permissionDecision values: "allow" or "deny"

---

8. hooks.json Format

Located at .claude/hooks.json or path specified in plugin.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. No production code without a failing test."
          }
        ]
      }
    ]
  }
}

Structure rules:

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

---

9. General Prompt Engineering

Layer order (imperative for complex prompts):

1. Role/persona — "You are a strict code reviewer..."
2. Context — relevant background, project state, constraints
3. Task — specific action to perform
4. Constraints — what to avoid, limits, edge cases
5. Output format — exact structure of the response

Few-shot examples: Include 2+ concrete input→output examples for any complex judgment task. Examples dramatically improve consistency.

Positive framing: State what to do. "Use imperative verbs" beats "Don't use passive voice." The brain processes prohibitions poorly under inference load (Pink Elephant effect).

Explicit output format: Every command and agent body should define exactly what the output should look like — section names, table formats, score displays, etc.

---

10. Naming Conventions

Item	Convention	Example
File names	kebab-case	tdd-guardian.md, pre-write-check.sh
Plugin names	kebab-case	nlpm, echo-sleuth
Skill references	plugin-name:skill-name	nlpm:conventions, tdd-guardian:rules
Rule files (ordered)	NN-kebab.md	01-formatting.md
Environment variable	SCREAMING_SNAKE	CLAUDE_PLUGIN_ROOT

Portable paths: Always use ${CLAUDE_PLUGIN_ROOT} when referencing files within a plugin (scripts, configs). Hardcoded absolute paths break portability.

---

11. 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:patterns"]

Hooks referencing scripts:

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

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

---

12. Memory File Conventions

Memory files are .md files that Claude Code writes and reads as persistent per-project knowledge.

Location:

~/.claude/projects/<project-slug>/memory/

Index file: MEMORY.md lives at the same level as individual memory files. It is a one-line-per-entry index, not a memory file itself. Each line references one memory file by filename.

Individual memory files MUST include YAML frontmatter:

---
name: "short identifier"
description: "one-line summary of what this memory contains"
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 — orphaned files (present in the directory but not in the index) are flagged by the scorer
• MEMORY.md itself is the index; it does not need frontmatter and is not scored as a memory file
• Memory files should not reference other files or functions that have since been deleted — stale references reduce the signal-to-noise ratio of the memory store

---

13. Rule Overrides in nlpm.local.md

Users can suppress or adjust individual rules in .claude/nlpm.local.md:

---
strictness: standard
score_threshold: 70
rule_overrides:
  R01: { max_penalty: -10 }     # reduce vague quantifier cap from -20 to -10
  R05: { threshold: 600 }       # allow skills up to 600 lines instead of 500
  R09: { min_examples: 1 }      # require only 1 example block instead of 2
  R10: { suppress: true }       # disable model tier checking entirely
  R23: { budget: 800 }          # increase rules budget from 500 to 800 lines
---

Override types:

Type	Effect	Example
suppress: true	Disable the rule entirely (penalty becomes 0)	R10: { suppress: true }
max_penalty: N	Cap the penalty at N (less negative = more lenient)	R01: { max_penalty: -10 }
threshold: N	Adjust numeric thresholds (line limits, counts)	R05: { threshold: 600 }
min_examples: N	Adjust minimum example counts	R09: { min_examples: 1 }

Rules not listed in rule_overrides use their defaults from nlpm:scoring.

---

Scope Note

This skill covers Claude Code plugin component schemas and conventions. It does NOT cover:

• Scoring/quality rubric -> see nlpm:scoring
• Anti-patterns and best practices catalog -> see nlpm:patterns
• General software engineering conventions outside Claude Code artifacts