conventions

Universal NL Programming Conventions

The cross-tool floor for all artifact schemas. Use this skill when scoring or writing any NL programming artifact regardless of which tool (Claude Code / Codex CLI / Antigravity) it targets.

Tool-specific overlays load on top of this universal floor:

• nlpm:conventions-claude — Claude Code artifacts (.claude/, plugin.json, etc.)
• nlpm:conventions-codex — Codex CLI artifacts (.codex/, .agents/, AGENTS.md)
• nlpm:conventions-antigravity — Antigravity (and legacy Gemini CLI) artifacts (.gemini/, .agent/)

The scorer loads the matching overlay per tier classification — see agents/scorer.md step 3.

Design rationale: analysis/multi-tool-design-2026-05.md.

1. SKILL.md — Cross-Tool Open Standard

SKILL.md is the Agent Skills open spec, stewarded by the Agentic AI Foundation under the Linux Foundation. Anthropic published the spec on 2025-12-18; OpenAI, Microsoft, Google adopted within 48 hours. By 2026-03, 32+ tools read the same SKILL.md format (Claude Code, Codex, Gemini CLI / Antigravity, Cursor, Kiro, Continue, etc.).

Authoritative reference: https://agentskills.io/specification

Required frontmatter (per the open spec):

• name — string; 1-64 chars, lowercase + hyphens only, MUST match parent directory name (no leading/trailing/consecutive hyphens).
• description — string; 1-1024 chars; should describe what the skill does AND when to use it.

Optional frontmatter (per the open spec):

• license — license name or reference to a bundled file.
• compatibility — environment requirements, max 500 chars (e.g., "Designed for Claude Code", "Requires Python 3.14+ and uv").
• metadata — arbitrary key-value mapping (author, version, etc. go here, NOT as top-level fields).
• allowed-tools — space-separated tool list (experimental in spec; tool-specific in practice — e.g., Bash(git:*) Read).

Tool-specific extensions to SKILL.md frontmatter live in the per-tool overlay skills. The scorer applies the universal spec rules to ALL SKILL.md files. Tool-specific overlay rules apply ONLY to files at the matching tool's canonical paths.

Skill paths (canonical, per tool):

Body rules (recommendations, not spec requirements):

• Keep under 500 lines — exceeding creates context bloat (spec recommends under 5000 tokens for the body, with overflow in references/).
• Reference material — imperatives belong in commands/agents.
• Include a scope note: what this skill covers and what it does NOT cover.
• Cross-reference related skills with their plugin:skill identifiers.

The spec explicitly says "no format restrictions" on the body — do NOT penalize SKILL.md files for missing ## Output or other section conventions. Those are tool-specific style preferences, not spec violations.

Supporting directories (per the spec):

• scripts/ — executable code (Python, Bash, JavaScript)
• references/ — additional docs loaded on demand
• assets/ — templates, images, data files

Progressive disclosure:

1. Metadata (~100 tokens): name + description loaded at startup for ALL skills.
2. Instructions (<5000 tokens): full SKILL.md body loaded when activated.
3. Resources: scripts/references/assets loaded only when needed.

2. AGENTS.md — Canonical Universal Memory File

Per nlpm decision (analysis/multi-tool-design-2026-05.md §5), AGENTS.md is the canonical universal memory file across all tools nlpm supports.

Tool-native support:

• Codex CLI: reads AGENTS.md natively. Hierarchical (root→cwd; closer overrides earlier). 32 KiB cap. ~/.codex/AGENTS.override.md for personal overlays.
• Antigravity (and Gemini CLI): reads GEMINI.md natively, but context.fileName setting accepts an array — set to ["AGENTS.md", "GEMINI.md"] to make it read AGENTS.md.
• Claude Code: reads CLAUDE.md natively, supports @file.md import syntax. The canonical pattern is a one-line CLAUDE.md containing @AGENTS.md.

Recommended pattern for multi-tool projects:

project-root/
├── AGENTS.md           # canonical content — all instructions live here
├── CLAUDE.md           # one line: @AGENTS.md
├── GEMINI.md           # one line: @AGENTS.md  (only if Gemini-native @-import works)
└── .gemini/settings.json  # set context.fileName: ["AGENTS.md"]

This is exactly how nlpm itself is structured (CLAUDE.md → @AGENTS.md).

Body conventions (universal):

• Open with a one-line project description.
• ## Architecture or ## Project Structure — what lives where.
• ## Build / ## Run / ## Test — verifiable commands.
• ## Prerequisites — required tools / versions / setup.
• ## Conventions — naming, style, patterns.

Tool-specific memory-file extensions (e.g., Claude Code's @-import syntax, Gemini's @{path} injection, Codex's project_doc_fallback_filenames) live in the per-tool overlays.

Agent workflow programs (recognized variant, no penalty rubric yet)

An agent workflow program is a single project-root Markdown file that drives an autonomous agent loop — imperative numbered steps with output formats and error paths, sitting between a memory file (AGENTS.md-shaped context) and a slash command (workflow with verifiable side effects). Karpathy's program.md in karpathy/autoresearch is the canonical example (audited 2026-05-28 at score ~90; see auditor/exemplars/karpathy-autoresearch.md). The README explicitly frames it as natural-language programming: "you are programming the program.md Markdown files that provide context to the AI agents."

nlpm recognizes the pattern but does not yet have a dedicated penalty rubric — the universal floor (R01 vague quantifiers, R03 positive framing, R09 prompt layers) + the command rules (R14–R17) + the memory-file rules (R33–R39) cover it adequately as a hybrid. A standalone rubric is deferred until N≥3 examples surface, per the same "don't build for an empty corpus" discipline applied to multi-tool discovery.

3. General Prompt Engineering

Universal patterns applicable to any NL artifact (commands, agents, skills, prompts) regardless of tool.

Layer order (imperative for complex prompts):

1. Role/persona — "You are a strict code reviewer..."
2. Context — project state, prior decisions, file paths, constraints
3. Task — specific action to perform
4. Constraints — what to avoid, limits, edge cases
5. Output format — exact structure of the response

Few-shot examples: Include 2+ concrete input→output examples for any complex judgment task. Examples dramatically improve consistency.

Positive framing: State what to do. "Use imperative verbs" beats "Don't use passive voice." The brain processes prohibitions poorly under inference load (Pink Elephant effect).

Explicit output format: Every command and agent body should define exactly what the output should look like — section names, table formats, score displays, etc.

4. Vague Quantifiers (R01)

The R01 rule penalizes unbounded quantifiers without measurable criteria. The penalty applies regardless of which tool the artifact targets.

Penalized terms: appropriate, relevant, as needed, sufficient, adequate, reasonable, properly, correctly, some, several, various.

Carve-outs (do NOT penalize):

• relevant in a markdown header (e.g., ## Relevant X).
• relevant to <named-scope> constructions (semantic "pertinent to").
• Any term followed by a measurable criterion clause (e.g., "appropriate to the SLO target of 99.9% uptime").

See nlpm:scoring for the full vague-quantifier penalty table and cap (-2 each, -20 cap).

5. Naming Conventions (universal)

Portable paths: Within a plugin, always reference files via the tool's plugin-root environment variable — ${CLAUDE_PLUGIN_ROOT} in Claude Code, ${PLUGIN_ROOT} in Codex (Codex additionally sets CLAUDE_PLUGIN_ROOT / CLAUDE_PLUGIN_DATA for compatibility with existing plugin hooks). Hardcoded absolute paths break portability.

Tool-specific naming details (e.g., the exact CLAUDE_PLUGIN_ROOT semantics) live in the per-tool overlays.

6. Rule Overrides (.claude/nlpm.local.md or equivalent)

The override system is universal. The configuration file path is per-tool:

Frontmatter format (identical across tools):

---
strictness: standard
score_threshold: 70
rule_overrides:
  R01: { max_penalty: -10 }     # reduce vague quantifier cap from -20 to -10
  R05: { threshold: 600 }       # allow skills up to 600 lines instead of 500
  R09: { min_examples: 1 }      # require only 1 example block instead of 2
  R10: { suppress: true }       # disable model tier checking entirely
  R23: { budget: 800 }          # increase rules budget from 500 to 800 lines
  R51: { enabled: true, vocabulary_skill: skills/myplugin/vocabulary/ }
---

Override types:

Rules not listed in rule_overrides use their defaults from nlpm:scoring. Rules that ship disabled (R51) contribute zero penalty unless enabled: true is set explicitly.

7. Universal Tool References

MCP tools follow the cross-tool pattern: mcp__<server-name>__<tool-name>. Example: mcp__mermaider__validate_syntax.

Per-tool built-in tool catalogs live in the overlays:

• Claude Code built-ins → nlpm:conventions-claude §16
• Codex CLI built-ins → nlpm:conventions-codex
• Antigravity built-ins → nlpm:conventions-antigravity

Scope Note

This skill covers the universal floor — conventions that apply regardless of which tool the artifact targets. It does NOT cover:

• Tool-specific schemas → see nlpm:conventions-claude / nlpm:conventions-codex / nlpm:conventions-antigravity
• Penalty tables → see nlpm:scoring
• Anti-patterns and best practices catalog → see nlpm:patterns
• General software engineering conventions outside NL programming artifacts