Skill

When to use

• User asks to create, rename, split, merge, or rewrite a ni skill, agent, or command
• A skill does not trigger, or triggers on unrelated prompts
• A SKILL.md grows past 300 lines or carries content another skill also needs
• User asks how ni is laid out, linked, validated, or installed

Overview

A skill is a reference guide for a proven technique, not a story about one task. It loads only when its description matches the prompt, so the description decides whether the body is ever read. Write the smallest body that changes behaviour.

Every ni skill fits one plugin. Same voice, same sections, same linking. A new skill that reads like its neighbours costs the reader nothing to learn.

Template: template.md. Copy it, then delete the sections you do not need.

Layout

natural-intelligence/
  .claude-plugin/plugin.json   manifest
  agents/<name>.md             subagents, spawned as ni:<name>
  commands/<name>.md           slash commands, run as /ni:<name>
  skills/<name>/SKILL.md       one skill per folder, name = folder
  skills/<name>/<topic>.md     reference file, linked from SKILL.md
  README.md                    skill, agent, and command tables

Names are short nouns or noun pairs, lowercase, hyphens: plan, tdd, code-review. Folder name equals frontmatter name. Claude exposes it as ni:<name>.

Frontmatter

---
name: <folder-name>
description: "Use when <triggers>. Also use when <more triggers>."
---

Description rules:

1. Triggers first. Say when to load. One short clause on what the skill is may precede it. Never summarise the workflow: a description that summarises the steps gets followed instead of the body.
2. Start with "Use when". Third person. Double quotes. Name under 64 characters.
3. List concrete symptoms, phrasings, file types, and tool names a prompt would contain.
4. Under 500 characters when possible, 1024 at most.

Not: description: "Prevents hallucinations by requiring evidence for all claims." Yes: description: "Use when analysing code, explaining behaviour, reviewing a change, or making any claim about how the code works."

Body

Sections in this order. Drop any that has nothing to say.

Voice: short plain prose. Full sentences under 20 words, active, imperative for instructions, one term per concept. No filler, no emoji, no decorative tables. Tables carry data or comparisons only.

Length: under 300 lines. Under 150 when the skill loads often. Move heavy reference (commands, API detail, long examples) to a sibling file and link it.

Examples: one "Not" line and one "Yes" line beat a paragraph. Code blocks for commands.

Snippets: ni runs on Linux, macOS, and Windows with or without WSL. Every command in a skill, agent, or command file follows the shell rules in onboarding.md: one command per line, no shell syntax, each shell's form on its own line where the invocation differs. No hooks, no script that needs one particular shell.

Linking

Link sibling skills with relative markdown links: tdd. Reference files link back to their skill: code-review. Mark hard dependencies:

• **REQUIRED BACKGROUND:** the [x](../x/SKILL.md) skill defines ...
• **REQUIRED SUB-SKILL:** use [tdd](../tdd/SKILL.md) for the failing test

Never repeat a rule that lives in another skill. Link it. One owner per rule.

Reference files sit next to SKILL.md and link from it directly, one level deep. No reference file links another reference file.

Agents are referenced by their spawn name in backticks: ni:investigator.

Agents

File agents/<name>.md. Frontmatter: name, description (when to spawn, what comes back), optional model (haiku for locate and review jobs), tools as a comma list. Body: role in one line, job, output contract as a code block, refusals as terminal first lines, auto-clarity note. Output contracts are the point: rows, not prose.

Commands

File commands/<name>.md. Frontmatter: description, optional argument-hint. Body is the prompt Claude receives. The placeholder ARGUMENTS with a dollar prefix carries the arguments (written out here because skills expand it too). Keep commands thin: point at a skill, do not restate rules. A command that needs a shell call prompts for approval, so prefer commands that only read and reason.

Verify and install

1. claude plugin validate . --strict from the repo root
2. bash .github/scripts/docs.test.sh: enforces the shell rules, links, and shipped tree
3. claude --plugin-dir . -p "..." to load from the working tree
4. Add the skill, agent, or command to the README table
5. Bump version in .claude-plugin/plugin.json: users only get updates on a version change
6. /reload-plugins in a running session, or start a new one
7. Commit with the git-conventions skill

Optional trigger test: run a prompt that should load the skill with --model haiku -p and ask which skills it used. Run one that should not. Adjust the description on a miss.

Boundaries

This skill covers ni only. Project skills under .claude/skills/ follow their project. Never write a skill for a one-off task or a project convention: those go in CLAUDE.md. Never duplicate a rule an existing skill owns.