Patterns

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:

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 improvement"), follow it immediately with one or more numeric examples that cover the trade-space corners (best case, worst case, neutral case). The principle becomes testable instead of aspirational.

Example (from karpathy/autoresearch program.md:37, scored 90/100 — see auditor/exemplars/karpathy-autoresearch.md for the full audit):

"All else being equal, simpler is better. … A 0.001 val_bpb improvement that adds 20 lines of hacky code? Probably not worth it. A 0.001 val_bpb improvement from deleting code? Definitely keep. An improvement of ~0 but much simpler code? Keep."

The principle "simpler is better" alone fails R22 enforceability — different agents weigh "simpler" differently. The three anchored examples define the trade-space (gain × complexity-cost) by worked corner cases, so any agent following the rule reaches the same call on a borderline case.

Apply when writing rules, agent constraints, or workflow instructions that include a subjective judgment word (small, meaningful, ugly, reasonable, simple, clean). Don't strip the subjective word — anchor it.

P11: Paired CAN/CANNOT Contract (R03)

When prohibitions are non-trivial, present capabilities and prohibitions as a paired list — "What you CAN do" / "What you CANNOT do" — rather than a stream of do nots. Each prohibition gains a positive complement; the agent reads both halves of the boundary in one pass.

Example (from karpathy/autoresearch program.md:25-31):

**What you CAN do:**
- Modify `train.py` — this is the only file you edit. Everything is fair game: model
  architecture, optimizer, hyperparameters, training loop, batch size, model size, etc.

**What you CANNOT do:**
- Modify `prepare.py`. It is read-only…
- Install new packages or add dependencies…
- Modify the evaluation harness…

What makes this strong: prohibitions without alternatives are A2's Pink Elephant trap; the paired pattern structurally avoids it. The "CAN" half also doubles as a positive scope statement ("Everything is fair game") that prevents the agent from being overly conservative.

Apply when an instruction set has more than two prohibitions on the same subject (file boundaries, tool boundaries, behavior boundaries). For a single prohibition, an inline "do X instead of Y" (P3) is enough.

P12: Autonomy Instruction + Rationale + Fallback Ladder (R03, R17)

When telling an agent to act autonomously, three pieces are required for the instruction to actually produce autonomous behavior: (1) state the rule clearly with example forbidden questions, (2) explain why in concrete terms the agent can reason about, (3) name the failure mode the agent is most likely to hit and give a numbered list of recovery moves before it encounters them. Bare "be autonomous" instructions produce timid agents that ask for permission.

Example (from karpathy/autoresearch program.md:112, scored 90/100 — see auditor/exemplars/karpathy-autoresearch.md):

"Once the experiment loop has begun (after the initial setup), do NOT pause to ask the human if you should continue. Do NOT ask 'should I keep going?' or 'is this a good stopping point?'. The human might be asleep, or gone from a computer and expects you to continue working indefinitely until you are manually stopped. You are autonomous. If you run out of ideas, think harder — read papers referenced in the code, re-read the in-scope files for new angles, try combining previous near-misses, try more radical architectural changes."

What makes this strong: the rule names the failure mode by quoting it ("'should I keep going?'"), the rationale grounds it in a concrete world-state ("human might be asleep"), and the four recovery moves (read papers / re-read files / combine near-misses / radical changes) cover the trade-space when the agent's first instinct (ask) is removed.

Apply when writing any instruction that asks an agent to operate without per-step human approval — long-running loops, overnight runs, batch processing, recursive workflows. Without the fallback ladder, the agent silently halts the first time it runs out of obvious moves.