Writing Skills

Scope: covers SKILL.md authoring. SKILL.md is the cross-tool open standard (agentskills.io) — the same file works in Claude Code (.claude/skills/), Codex CLI (.agents/skills/), and Antigravity (.agent/skills/). Only name and description are required by the spec; per-tool extras (Claude's model:/allowed-tools:, Codex's agents/openai.yaml sidecar) live in [[nlpm:conventions-claude]] / [[nlpm:conventions-codex]] / [[nlpm:conventions-antigravity]]. For agent writing, see [[writing-agents]]. For plugin architecture, see [[writing-plugins]].

1. The Description is Everything

The description field determines when Claude loads this skill. It is not a summary -- it is a trigger mechanism.

Bad (score 55):

description: "Helpful skill for React development"

Good (score 95):

description: "Use when building React components, debugging re-renders, optimizing performance with useMemo/useCallback, or fixing hook dependency arrays"

Description Checklist