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.

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."

Real-world example: AgriciDaniel-claude-ads, ChromeDevTools-chrome-devtools-mcp, Xquik-dev-x-twitter-scraper, blader-humanizer, coreyhaines31-marketingskills, google-labs-code-stitch-skills, kazukinagata-shinkoku, krodak-clickup-cli, nexu-io-open-design, slavingia-skills

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

Real-world example: Kamalnrf-claude-plugins, forrestchang-andrej-karpathy-skills, krodak-clickup-cli, multica-ai-andrej-karpathy-skills

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.

Real-world example: karpathy-autoresearch

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."

Real-world example: 2389-research-review-squad, 2389-research-simmer, AgriciDaniel-claude-ads, AgriciDaniel-claude-seo, BayramAnnakov-claude-reflect, ChromeDevTools-chrome-devtools-mcp, CloudAI-X-claude-workflow-v2, Dammyjay93-interface-design, Jeffallan-claude-skills, JimLiu-baoyu-skills, JuliusBrussee-cavekit, JuliusBrussee-caveman, Kamalnrf-claude-plugins, Master-cai-Research-Paper-Writing-Skills, MemPalace-mempalace, OthmanAdi-planning-with-files, RKiding-Awesome-finance-skills, ReflexioAI-claude-smart, SukinShetty-Nemp-memory, The-Vibe-Company-companion, Xquik-dev-x-twitter-scraper, Yuan1z0825-nature-skills, addyosmani-web-quality-skills, agenticnotetaking-arscontexta, alexgreensh-token-optimizer, alizarion-openclaw-claude-code-plugin, antfu-skills, astral-sh-claude-code-plugins, axtonliu-axton-obsidian-visual-skills, backnotprop-plannotator, blader-humanizer, coreyhaines31-marketingskills, czlonkowski-n8n-skills, data-goblin-power-bi-agentic-development, dontbesilent2025-dbskill, evo-hq-evo, expo-skills, firecrawl-firecrawl-claude-plugin, fivetaku-fablize, forrestchang-andrej-karpathy-skills, google-labs-code-stitch-skills, google-skills, itsmostafa-aws-agent-skills, jnMetaCode-superpowers-zh, kazukinagata-shinkoku, kepano-obsidian-skills, krodak-clickup-cli, lackeyjb-playwright-skill, m1heng-claude-plugin-weixin, mattpocock-skills, mem0ai-mem0, multica-ai-andrej-karpathy-skills, muratcankoylan-ralph-wiggum-marketer, nagisanzenin-claude-code-production-grade-plugin, nexu-io-open-design, nicknisi-claude-plugins, numman-ali-n-skills, ooiyeefei-ccc, openai-codex-plugin-cc, pe-menezes-fin-claude-plugin, shinpr-claude-code-workflows, slavingia-skills, softaworks-agent-toolkit, taishi-i-awesome-japanese-nlp-resources, tanweai-pua, team-attention-plugins-for-claude-natives, tech-leads-club-agent-skills, teng-lin-notebooklm-py, timescale-pg-aiguide, tirth8205-code-review-graph, viticci-shortcuts-playground-plugin, vladikk-modularity, xiaolai-grill-for-claude, ykdojo-claude-code-tips

R05. Under 500 lines. Over 500 = context bloat. Split into scoped sub-skills with cross-references.

Real-world example: 2389-research-review-squad, AgriciDaniel-claude-seo, BayramAnnakov-claude-reflect, ChromeDevTools-chrome-devtools-mcp, CloudAI-X-claude-workflow-v2, Dammyjay93-interface-design, Jeffallan-claude-skills, JimLiu-baoyu-skills, MemPalace-mempalace, OthmanAdi-planning-with-files, RKiding-Awesome-finance-skills, Xquik-dev-x-twitter-scraper, Yuan1z0825-nature-skills, addyosmani-web-quality-skills, alexgreensh-token-optimizer, alizarion-openclaw-claude-code-plugin, antfu-skills, astral-sh-claude-code-plugins, axtonliu-axton-obsidian-visual-skills, data-goblin-power-bi-agentic-development, dontbesilent2025-dbskill, evo-hq-evo, expo-skills, firecrawl-firecrawl-claude-plugin, fivetaku-fablize, forrestchang-andrej-karpathy-skills, google-labs-code-stitch-skills, google-skills, htdt-godogen, itsmostafa-aws-agent-skills, kepano-obsidian-skills, krodak-clickup-cli, lackeyjb-playwright-skill, m1heng-claude-plugin-weixin, mattpocock-skills, mem0ai-mem0, multica-ai-andrej-karpathy-skills, muratcankoylan-ralph-wiggum-marketer, nagisanzenin-claude-code-production-grade-plugin, nexu-io-open-design, nicknisi-claude-plugins, numman-ali-n-skills, slavingia-skills, softaworks-agent-toolkit, taishi-i-awesome-japanese-nlp-resources, tech-leads-club-agent-skills, tirth8205-code-review-graph, viticci-shortcuts-playground-plugin, vladikk-modularity, ykdojo-claude-code-tips

R06. Code examples must be runnable. Not pseudocode. Show the problem, then the solution, in real syntax.

Real-world example: 2389-research-simmer, AgriciDaniel-claude-ads, BayramAnnakov-claude-reflect, ChromeDevTools-chrome-devtools-mcp, CloudAI-X-claude-workflow-v2, CoderGamester-mcp-unity, Jeffallan-claude-skills, JimLiu-baoyu-skills, JuliusBrussee-cavekit, JuliusBrussee-caveman, Kamalnrf-claude-plugins, Master-cai-Research-Paper-Writing-Skills, MemPalace-mempalace, RKiding-Awesome-finance-skills, ReflexioAI-claude-smart, Xquik-dev-x-twitter-scraper, YishenTu-claudian, addyosmani-web-quality-skills, agenticnotetaking-arscontexta, alexgreensh-token-optimizer, alizarion-openclaw-claude-code-plugin, antfu-skills, astral-sh-claude-code-plugins, axtonliu-axton-obsidian-visual-skills, backnotprop-plannotator, blader-humanizer, coreyhaines31-marketingskills, czlonkowski-n8n-skills, data-goblin-power-bi-agentic-development, evo-hq-evo, expo-skills, firecrawl-firecrawl-claude-plugin, fivetaku-fablize, google-labs-code-stitch-skills, google-skills, itsmostafa-aws-agent-skills, jnMetaCode-superpowers-zh, kazukinagata-shinkoku, kepano-obsidian-skills, krodak-clickup-cli, lackeyjb-playwright-skill, m1heng-claude-plugin-weixin, mattpocock-skills, multica-ai-andrej-karpathy-skills, muratcankoylan-ralph-wiggum-marketer, nexu-io-open-design, numman-ali-n-skills, shinpr-claude-code-workflows, softaworks-agent-toolkit, taishi-i-awesome-japanese-nlp-resources, tanweai-pua, tech-leads-club-agent-skills, teng-lin-notebooklm-py, timescale-pg-aiguide, tirth8205-code-review-graph, xiaolai-grill-for-claude, ykdojo-claude-code-tips

R07. Scope note when related skills exist. "Covers X. For Y, see [[other-skill]]." Without this, Claude doesn't know which skill to pick.

Real-world example: 2389-research-review-squad, 2389-research-simmer, AgriciDaniel-claude-ads, AgriciDaniel-claude-seo, ChromeDevTools-chrome-devtools-mcp, CloudAI-X-claude-workflow-v2, Dammyjay93-interface-design, Jeffallan-claude-skills, JuliusBrussee-cavekit, Master-cai-Research-Paper-Writing-Skills, OthmanAdi-planning-with-files, ReflexioAI-claude-smart, The-Vibe-Company-companion, Xquik-dev-x-twitter-scraper, Yuan1z0825-nature-skills, addyosmani-web-quality-skills, alexgreensh-token-optimizer, alizarion-openclaw-claude-code-plugin, axtonliu-axton-obsidian-visual-skills, backnotprop-plannotator, coreyhaines31-marketingskills, czlonkowski-n8n-skills, data-goblin-power-bi-agentic-development, dontbesilent2025-dbskill, evo-hq-evo, expo-skills, firecrawl-firecrawl-claude-plugin, google-labs-code-stitch-skills, htdt-godogen, jnMetaCode-superpowers-zh, kazukinagata-shinkoku, kepano-obsidian-skills, lackeyjb-playwright-skill, mattpocock-skills, mem0ai-mem0, muratcankoylan-ralph-wiggum-marketer, nagisanzenin-claude-code-production-grade-plugin, numman-ali-n-skills, ooiyeefei-ccc, openai-codex-plugin-cc, pe-menezes-fin-claude-plugin, shinpr-claude-code-workflows, slavingia-skills, softaworks-agent-toolkit, taishi-i-awesome-japanese-nlp-resources, team-attention-plugins-for-claude-natives, tech-leads-club-agent-skills, timescale-pg-aiguide, viticci-shortcuts-playground-plugin, vladikk-modularity

R08. Patterns over theory. Teach what to do in specific situations, not abstract concepts.

Real-world example: 2389-research-review-squad, 2389-research-simmer, AgriciDaniel-claude-ads, AgriciDaniel-claude-seo, BayramAnnakov-claude-reflect, ChromeDevTools-chrome-devtools-mcp, CloudAI-X-claude-workflow-v2, Dammyjay93-interface-design, Jeffallan-claude-skills, JimLiu-baoyu-skills, JuliusBrussee-cavekit, JuliusBrussee-caveman, Kamalnrf-claude-plugins, Master-cai-Research-Paper-Writing-Skills, MemPalace-mempalace, OthmanAdi-planning-with-files, RKiding-Awesome-finance-skills, ReflexioAI-claude-smart, SukinShetty-Nemp-memory, The-Vibe-Company-companion, Xquik-dev-x-twitter-scraper, YishenTu-claudian, Yuan1z0825-nature-skills, addyosmani-web-quality-skills, agenticnotetaking-arscontexta, alexgreensh-token-optimizer, alizarion-openclaw-claude-code-plugin, antfu-skills, astral-sh-claude-code-plugins, axtonliu-axton-obsidian-visual-skills, backnotprop-plannotator, blader-humanizer, coreyhaines31-marketingskills, czlonkowski-n8n-skills, data-goblin-power-bi-agentic-development, dontbesilent2025-dbskill, evo-hq-evo, expo-skills, firecrawl-firecrawl-claude-plugin, fivetaku-fablize, forrestchang-andrej-karpathy-skills, google-labs-code-stitch-skills, google-skills, htdt-godogen, itsmostafa-aws-agent-skills, jarrodwatts-claude-hud, jnMetaCode-superpowers-zh, kazukinagata-shinkoku, kepano-obsidian-skills, krodak-clickup-cli, lackeyjb-playwright-skill, m1heng-claude-plugin-weixin, mattpocock-skills, mem0ai-mem0, multica-ai-andrej-karpathy-skills, muratcankoylan-ralph-wiggum-marketer, nagisanzenin-claude-code-production-grade-plugin, nexu-io-open-design, nicknisi-claude-plugins, numman-ali-n-skills, ooiyeefei-ccc, openai-codex-plugin-cc, pe-menezes-fin-claude-plugin, shinpr-claude-code-workflows, slavingia-skills, softaworks-agent-toolkit, taishi-i-awesome-japanese-nlp-resources, tanweai-pua, team-attention-plugins-for-claude-natives, tech-leads-club-agent-skills, teng-lin-notebooklm-py, timescale-pg-aiguide, tirth8205-code-review-graph, viticci-shortcuts-playground-plugin, vladikk-modularity, xiaolai-codex-toolkit-for-claude, ykdojo-claude-code-tips

Agents

R09. <example> blocks are mandatory. Minimum 2. Each: Context (what user is doing) + user message + assistant response. Without them, triggering is unreliable.

Bad: <example>\nContext: User needs help\nuser: "help me"\nassistant: "I'll help."\n</example> Good: <example>\nContext: Developer refactoring auth module before PR\nuser: "Check if the auth changes have any security issues before I merge"\nassistant: "I'll dispatch the security-reviewer to audit the auth changes for vulnerabilities."\n</example>

Real-world example: data-goblin-power-bi-agentic-development, nicknisi-claude-plugins, ooiyeefei-ccc, xiaolai-codex-toolkit-for-claude, xiaolai-grill-for-claude

R10. Model must match task complexity. haiku = mechanical (parsing, counting). sonnet = reasoning (analysis, review). opus = complex judgment (orchestration). Wrong tier wastes money or produces weak results.

Real-world example: AgriciDaniel-claude-ads, JuliusBrussee-caveman, leowux-pony, xiaolai-grill-for-claude

R11. Tools follow least-privilege. Only tools the body references. Write/Edit on a read-only agent is a security smell.

Real-world example: AgriciDaniel-claude-ads, JuliusBrussee-caveman, leowux-pony, pe-menezes-fin-claude-plugin, tanweai-pua, xiaolai-codex-toolkit-for-claude, xiaolai-grill-for-claude

R12. Output format defined in body. Every agent must specify its response structure. Without it, output varies between invocations.

Real-world example: AgriciDaniel-claude-seo, CloudAI-X-claude-workflow-v2, JuliusBrussee-caveman, leowux-pony, nicknisi-claude-plugins, ooiyeefei-ccc, pe-menezes-fin-claude-plugin, shinpr-claude-code-workflows, team-attention-plugins-for-claude-natives, xiaolai-codex-toolkit-for-claude, xiaolai-grill-for-claude

R13. System prompt structure: mission → steps → boundaries → format. Mission in first 2 sentences. Then numbered instructions. Then what NOT to do. Then output template.

Real-world example: AgriciDaniel-claude-seo, data-goblin-power-bi-agentic-development, evo-hq-evo, leowux-pony, viticci-shortcuts-playground-plugin, xiaolai-codex-toolkit-for-claude

Commands

R14. Steps must be numbered. Multi-step workflows in unnumbered prose are ambiguous.

Real-world example: BayramAnnakov-claude-reflect, SukinShetty-Nemp-memory, jarrodwatts-claude-hud, karpathy-autoresearch, mattpocock-skills, nicknisi-claude-plugins, uppinote20-claude-dashboard

R15. Handle empty input. What happens when $ARGUMENTS is blank? Default behavior or clear error.

Real-world example: BayramAnnakov-claude-reflect, SukinShetty-Nemp-memory, agenticnotetaking-arscontexta, karpathy-autoresearch, taishi-i-awesome-japanese-nlp-resources, uppinote20-claude-dashboard

R16. Define output format. Report template with exact structure. Not "show the results."

Real-world example: BayramAnnakov-claude-reflect, CloudAI-X-claude-workflow-v2, Dammyjay93-interface-design, OthmanAdi-planning-with-files, SukinShetty-Nemp-memory, agenticnotetaking-arscontexta, jarrodwatts-claude-hud, karpathy-autoresearch, openai-codex-plugin-cc, quant-sentiment-ai-claude-equity-research, taishi-i-awesome-japanese-nlp-resources, uppinote20-claude-dashboard

R17. Specify error paths. Missing files, bad data, unreadable input — each needs a defined response.

Real-world example: JuliusBrussee-cavekit, SukinShetty-Nemp-memory, jarrodwatts-claude-hud, karpathy-autoresearch, ooiyeefei-ccc, xiaolai-codex-toolkit-for-claude

R18. argument-hint when command takes input. Shows usage pattern in /help. Omit for zero-argument commands.

Real-world example: SukinShetty-Nemp-memory, agenticnotetaking-arscontexta, openai-codex-plugin-cc, quant-sentiment-ai-claude-equity-research, uppinote20-claude-dashboard

Shared Partials

R19. user-invocable: false is mandatory. Without it, the partial appears as a user command.

R20. description must state purpose. What the partial does, which commands use it.

Rules (.claude/rules/)

R21. Bold imperative + rationale. Three parts: what to do, what goes wrong without it, why. **Use X.** Without it, Y breaks because Z.

Bad: Don't use any. Good: **Use specific types instead of any.** Without specific types, TypeScript's compiler can't catch type errors at build time, and refactoring becomes unsafe because callers and callees disagree silently.

Real-world example: firecrawl-firecrawl-claude-plugin

R22. Must be enforceable. If you can't verify compliance in a code review, it's not a rule. Vague rules waste tokens.

Real-world example: [ReflexioAI-claude-smart](../../../auditor/exemplars/ReflexioAI-cl

…(truncated)