rules

# 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-files.md), [RKiding-Awesome-finance-skills](../../../auditor/exemplars/RKiding-Awesome-finance-skills.md), [ReflexioAI-claude-smart](../../../auditor/exemplars/ReflexioAI-claude-smart.md), [SukinShetty-Nemp-memory](../../../auditor/exemplars/SukinShetty-Nemp-memory.md), [The-Vibe-Company-companion](../../../auditor/exemplars/The-Vibe-Company-companion.md), [TheDecipherist-claude-code-mastery](../../../auditor/exemplars/TheDecipherist-claude-code-mastery.md), [Xquik-dev-x-twitter-scraper](../../../auditor/exemplars/Xquik-dev-x-twitter-scraper.md), [Yuan1z0825-nature-skills](../../../auditor/exemplars/Yuan1z0825-nature-skills.md), [addyosmani-web-quality-skills](../../../auditor/exemplars/addyosmani-web-quality-skills.md), [agenticnotetaking-arscontexta](../../../auditor/exemplars/agenticnotetaking-arscontexta.md), [alexgreensh-token-optimizer](../../../auditor/exemplars/alexgreensh-token-optimizer.md), [alizarion-openclaw-claude-code-plugin](../../../auditor/exemplars/alizarion-openclaw-claude-code-plugin.md), [antfu-skills](../../../auditor/exemplars/antfu-skills.md), [astral-sh-claude-code-plugins](../../../auditor/exemplars/astral-sh-claude-code-plugins.md), [axtonliu-axton-obsidian-visual-skills](../../../auditor/exemplars/axtonliu-axton-obsidian-visual-skills.md), [backnotprop-plannotator](../../../auditor/exemplars/backnotprop-plannotator.md), [bergside-awesome-design-skills](../../../auditor/exemplars/bergside-awesome-design-skills.md), [blader-humanizer](../../../auditor/exemplars/blader-humanizer.md), [coreyhaines31-marketingskills](../../../auditor/exemplars/coreyhaines31-marketingskills.md), [czlonkowski-n8n-skills](../../../auditor/exemplars/czlonkowski-n8n-skills.md), [data-goblin-power-bi-agentic-development](../../../auditor/exemplars/data-goblin-power-bi-agentic-development.md), [dontbesilent2025-dbskill](../../../auditor/exemplars/dontbesilent2025-dbskill.md), [earthtojake-text-to-cad](../../../auditor/exemplars/earthtojake-text-to-cad.md), [evo-hq-evo](../../../auditor/exemplars/evo-hq-evo.md), [expo-skills](../../../auditor/exemplars/expo-skills.md), [firecrawl-firecrawl-claude-plugin](../../../auditor/exemplars/firecrawl-firecrawl-claude-plugin.md), [fivetaku-fablize](../../../auditor/exemplars/fivetaku-fablize.md), [forrestchang-andrej-karpathy-skills](../../../auditor/exemplars/forrestchang-andrej-karpathy-skills.md), [gamedev-skills-awesome-gamedev-agent-skills](../../../auditor/exemplars/gamedev-skills-awesome-gamedev-agent-skills.md), [gemini-cli-extensions-conductor](../../../auditor/exemplars/gemini-cli-extensions-conductor.md), [google-labs-code-stitch-skills](../../../auditor/exemplars/google-labs-code-stitch-skills.md), [google-skills](../../../auditor/exemplars/google-skills.md), [greensock-gsap-skills](../../../auditor/exemplars/greensock-gsap-skills.md), [huggingface-skills](../../../auditor/exemplars/huggingface-skills.md), [itsmostafa-aws-agent-skills](../../../auditor/exemplars/itsmostafa-aws-agent-skills.md), [jnMetaCode-superpowers-zh](../../../auditor/exemplars/jnMetaCode