/patterns

name: patterns
description: "NL artifact anti-patterns: vague quantifiers, bare prohibitions, oversized skills."
version: 0.1.0
user-invocable: false

NL Programming Patterns

Best practices and anti-patterns for writing NL programming artifacts (Claude Code, Codex CLI, Antigravity). Each pattern includes a rationale and a concrete example. The patterns are tool-agnostic — they describe how to write effective natural-language instructions, not tool-specific schemas. Use this skill when authoring or reviewing skills, agents, commands, rules, or hooks.

**Notation:** `$+{CLAUDE_PLUGIN_ROOT}` in this file is Claude Code's plugin-root variable, split by a `+` so Claude Code does not replace it with a path when it loads this skill; the real token has no `+` (`nlpm:conventions-claude` §2.4).

---

Patterns (Use These)

P1: Trigger-Optimized Descriptions (R04)

Write agent and skill descriptions with 3+ specific trigger phrases rather than a single generic one-liner. Claude uses description text to decide when to invoke an agent; richer vocabulary improves recall.

**Good:**

description: |
  Scores NL artifacts and reports findings. Use this agent when scoring plugin
  artifacts, checking prompts for quality findings, checking command
  completeness, or auditing skill descriptions for vagueness.

**Bad:**

description: "Analyzes files"

The bad example won't trigger reliably — "analyzes files" matches too broadly and too vaguely.

---

P2: Example-Driven Agents (R09)

Include one well-chosen `<example>` block in the agent description — realistic Context, user turn, and assistant response — plus a sentence naming what the agent is not for ("Not for …; use <sibling>"). The description is the only thing Claude sees when choosing an agent and it is loaded on every turn, so examples belong in the description (not the body), and each extra example costs always-on context. Keep the whole description ≤1,200 characters.

**Minimum structure per example:**

<example>
Context: <situation that would trigger this agent>
user: <what the user or command says>
assistant: <what this agent does in response>
</example>

**Pick the example that carries the main positive trigger.** Add a second only when a distinct trigger (e.g. a command-as-orchestrator invocation) cannot be stated in the prose; state secondary trigger phrases in the prose instead.

---

P3: Imperative + Rationale Rules (R03, R21)

Write rules as "**Do X** because Y" not "Don't do Z". The Pink Elephant effect: telling someone not to think of a pink elephant makes them think of it. Prohibitions without alternatives are hard to follow under inference load.

**Good:**

**Use `$+{CLAUDE_PLUGIN_ROOT}` for all intra-plugin file references.**

Because absolute paths break when the plugin is installed by different users
or on different machines, portable path variables ensure the plugin works
everywhere it is installed.

**Bad:**

Don't hardcode absolute paths in hooks or scripts.

---

P4: Layered Prompts (R40)

Structure complex command and agent bodies in this order: 1. Role/persona 2. Context (what you know, what you've been given) 3. Task (specific action) 4. Constraints (limits, edge cases, what to avoid) 5. Output format (exact structure)

Mixing these layers — especially burying the task in the middle of constraints — reduces response quality.

---

P5: Graduated Model Selection (R10)

Match model tier to task complexity:

| Model | Best for | |-------|---------| | `haiku` | Parsing, formatting, file discovery, classification, pattern matching | | `sonnet` | Analysis, reasoning, code review, multi-step judgment, scoring | | `opus` | Complex judgment requiring deep synthesis, orchestration of many agents |

Using opus for a file-glob scan wastes tokens with no quality improvement. Using haiku for nuanced quality scoring produces unreliable results.

---

P6: Scoped Skills (R05, R07)

Keep each skill under 500 lines with a clearly bounded scope. Include a "Scope Note" section at the bottom stating what the skill covers and what it does NOT cover, with cross-references to related skills (`plugin:skill` format).

Benefits:

• Prevents context bloat when multiple skills are loaded simultaneously
• Makes skills easier to update without cascading effects
• Enables precise skill selection in agent frontmatter

---

P7: Least-Privilege Tools (R11)

Only list tools in `allowed-tools` (commands) or `tools` (agents) that the body actually uses. Declaring unused tools is misleading and may grant unintended capabilities.

**Good:**

tools: ["Glob", "Read"]

(for a scanner that only discovers and reads files)

**Bad:**

tools: ["Glob", "Read", "Write", "Edit", "Bash", "WebSearch"]

(for the same scanner)

---

P8: Explicit Output Formats (R12, R16, R41)

Every command and agent body should define the exact output structure. Don't leave format to inference — specify section names, table columns, score display format, and summary location.

**Example output format spec in a command body:**

Report format:
## Summary
Total artifacts: N | Pass (≥70): N | Fail (<70): N

## Results
| File | Type | Score | Top Issues |
|------|------|-------|------------|
| path/to/file.md | agent | 87 | ... |

## Details
One subsection per file with full penalty breakdown.

---

P9: Error Path Coverage (R17)

Handle the three failure modes explicitly in every command and agent: 1. **Empty input** — no files found, no argument provided 2. **Missing files** — referenced file doesn't exist 3. **Malformed data** — YAML parse errors, invalid JSON, truncated content

Each failure mode should produce a clear, actionable error message — not a silent no-op or a generic "something went wrong."

---

P10: Numeric Anchoring of Subjective Principles (R22)

When stating a principle that has a subjective threshold ("simpler is better", "small change", "meaningful