/rules

name: rules
description: "The 50 NL programming rules (R01-R50) for skills, agents, commands, hooks, prompts."
version: 0.2.0
user-invocable: false

The Rules of Natural Language Programming

> These rules govern how to write NL artifacts that Claude Code and other LLMs consume. They are enforced by `/nlpm:score` (penalty-based) and referenced by `/nlpm:fix` (auto-repair). When writing any NL artifact, follow these rules. > > **Notation:** `$+ARGUMENTS` and `$+{CLAUDE_PLUGIN_ROOT}` in this file are Claude Code's argument token and plugin-root variable, split by a `+` so Claude Code does not replace them when it loads this skill; the real tokens have no `+` (`nlpm:conventions-claude` §2.4).

---

Universal (all artifacts)

**R01. No vague quantifiers without criteria.** "appropriate", "relevant", "as needed", "sufficient", "adequate", "reasonable", "properly", "correctly", "some", "several", "various" are meaningless without specifics. Replace with measurable criteria. Penalty: -2 each, cap -20.

Bad: "Use appropriate error handling." Good: "Return `Result<T, AppError>` from all API handlers. Map errors to HTTP status codes via the `From<AppError> for StatusCode` impl."

Mention versus use: a vague term presented as a literal token that the clause explicitly instructs a reader or tool to detect, flag, or replace is data, not an instruction, and is not counted (see the exclusion note in `nlpm:scoring`). Backticks alone do not qualify.

<!-- nlpm-exemplar-citation:begin --> > Real-world example: [AgriciDaniel-claude-ads](../../../auditor/exemplars/AgriciDaniel-claude-ads.md), [ChromeDevTools-chrome-devtools-mcp](../../../auditor/exemplars/ChromeDevTools-chrome-devtools-mcp.md), [Graphify-Labs-graphify](../../../auditor/exemplars/Graphify-Labs-graphify.md), [Xquik-dev-x-twitter-scraper](../../../auditor/exemplars/Xquik-dev-x-twitter-scraper.md), [blader-humanizer](../../../auditor/exemplars/blader-humanizer.md), [coreyhaines31-marketingskills](../../../auditor/exemplars/coreyhaines31-marketingskills.md), [earthtojake-text-to-cad](../../../auditor/exemplars/earthtojake-text-to-cad.md), [google-labs-code-stitch-skills](../../../auditor/exemplars/google-labs-code-stitch-skills.md), [greensock-gsap-skills](../../../auditor/exemplars/greensock-gsap-skills.md), [kazukinagata-shinkoku](../../../auditor/exemplars/kazukinagata-shinkoku.md), [krodak-clickup-cli](../../../auditor/exemplars/krodak-clickup-cli.md), [larksuite-cli](../../../auditor/exemplars/larksuite-cli.md), [nexu-io-open-design](../../../auditor/exemplars/nexu-io-open-design.md), [prompt-security-clawsec](../../../auditor/exemplars/prompt-security-clawsec.md), [realrossmanngroup-no_ai_slop_writing_rules](../../../auditor/exemplars/realrossmanngroup-no_ai_slop_writing_rules.md), [slavingia-skills](../../../auditor/exemplars/slavingia-skills.md), [tintinweb-pi-subagents](../../../auditor/exemplars/tintinweb-pi-subagents.md) <!-- nlpm-exemplar-citation:end -->

**R02. Every line must earn its tokens.** Context window is finite. If a line doesn't change Claude's behavior, delete it.

<!-- nlpm-exemplar-citation:begin --> > Real-world example: [Kamalnrf-claude-plugins](../../../auditor/exemplars/Kamalnrf-claude-plugins.md), [bergside-awesome-design-skills](../../../auditor/exemplars/bergside-awesome-design-skills.md), [forrestchang-andrej-karpathy-skills](../../../auditor/exemplars/forrestchang-andrej-karpathy-skills.md), [krodak-clickup-cli](../../../auditor/exemplars/krodak-clickup-cli.md), [multica-ai-andrej-karpathy-skills](../../../auditor/exemplars/multica-ai-andrej-karpathy-skills.md) <!-- nlpm-exemplar-citation:end -->

**R03. Positive framing over prohibitions.** "Use X" not "Don't use Y." The Pink Elephant effect: Claude fixates on prohibited things and sometimes does them anyway.

<!-- nlpm-exemplar-citation:begin --> > Real-world example: [bergside-awesome-design-skills](../../../auditor/exemplars/bergside-awesome-design-skills.md), [greensock-gsap-skills](../../../auditor/exemplars/greensock-gsap-skills.md), [karpathy-autoresearch](../../../auditor/exemplars/karpathy-autoresearch.md), [larksuite-cli](../../../auditor/exemplars/larksuite-cli.md) <!-- nlpm-exemplar-citation:end -->

---

Skills (SKILL.md)

**R04. Description is a trigger, not a summary.** 3+ specific action phrases matching real user queries. "Use when debugging React re-renders, fixing hook dependency arrays, optimizing with useMemo" — not "Helpful React skill."

<!-- nlpm-exemplar-citation:begin --> > Real-world example: [2389-research-review-squad](../../../auditor/exemplars/2389-research-review-squad.md), [2389-research-simmer](../../../auditor/exemplars/2389-research-simmer.md), [AgriciDaniel-claude-ads](../../../auditor/exemplars/AgriciDaniel-claude-ads.md), [AgriciDaniel-claude-seo](../../../auditor/exemplars/AgriciDaniel-claude-seo.md), [BayramAnnakov-claude-reflect](../../../auditor/exemplars/BayramAnnakov-claude-reflect.md), [ChromeDevTools-chrome-devtools-mcp](../../../auditor/exemplars/ChromeDevTools-chrome-devtools-mcp.md), [CloudAI-X-claude-workflow-v2](../../../auditor/exemplars/CloudAI-X-claude-workflow-v2.md), [Dammyjay93-interface-design](../../../auditor/exemplars/Dammyjay93-interface-design.md), [Graphify-Labs-graphify](../../../auditor/exemplars/Graphify-Labs-graphify.md), [Jeffallan-claude-skills](../../../auditor/exemplars/Jeffallan-claude-skills.md), [JimLiu-baoyu-skills](../../../auditor/exemplars/JimLiu-baoyu-skills.md), [JuliusBrussee-cavekit](../../../auditor/exemplars/JuliusBrussee-cavekit.md), [JuliusBrussee-caveman](../../../auditor/exemplars/JuliusBrussee-caveman.md), [Kamalnrf-claude-plugins](../../../auditor/exemplars/Kamalnrf-claude-plugins.md), [Master-cai-Research-Paper-Writing-Skills](../../../auditor/exemplars/Master-cai-Research-Paper-Writing-Skills.md), [MemPalace-mempalace](../../../auditor/exemplars/MemPalace-mempalace.md), [OthmanAdi-planning-with-files](../../../auditor/exemplars/OthmanAdi-planning-with