/conventions

name: conventions
description: "Universal NL conventions: SKILL.md open spec, AGENTS.md, vague quantifiers, naming."
version: 0.2.1
user-invocable: false

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.

**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).

**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):**

| Tool | Path | |---|---| | Open-spec (cross-tool) | `.agents/skills/<name>/SKILL.md` | | Claude Code | `.claude/skills/<name>/SKILL.md` | | Codex CLI | `.agents/skills/<name>/SKILL.md` | | Antigravity | `<workspace>/.agent/skills/<name>/SKILL.md` (singular) AND `.agents/skills/<name>/SKILL.md` (cross-tool alias) | | Gemini CLI (legacy) | `.gemini/skills/<name>/SKILL.md` | | Continue, Cursor, Kiro | `.<tool>/skills/<name>/SKILL.md` |

**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 `AGENTS.md` natively from 2.1.277, but only when no `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` exists in the working directory or any directory above it (`~/.claude/CLAUDE.md` does not count). Older versions read only `CLAUDE.md`, which supports `@file.md` imports — there the compatibility pattern is a one-line `CLAUDE.md` containing `@AGENTS.md`. Plugin repositories ship `AGENTS.md` alone: `claude plugin validate` warns that a `CLAUDE.md` at the plugin root is not loaded as plugin context.

**Recommended pattern for multi-tool projects:**

project-root/
├── AGENTS.md           # canonical content — all instructions live here
├── CLAUDE.md           # only for Claude Code < 2.1.277: one line, @AGENTS.md (omit in plugin repos)
├── 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: `AGENTS.md` alone, which Claude Code reads natively.

**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