Reference · Syntax card

SKILL.md and sub-agents

The two files you will write most often. Copy, edit, ship.

A skill

Location: .claude/skills/<name>/SKILL.md

---
name: triage
description: Read yesterday's CI failures, open issues and recent
  commits, then write findings to LOOP.md. Use for the daily
  morning triage run.
---

# Daily triage

1. `gh run list --limit 20 --json conclusion,name,createdAt`
2. `gh issue list --state open --label bug`
3. `git log --since=yesterday --oneline`

Write each finding to `LOOP.md` under `## Open`, one line each,
with the evidence link. Change no source files in this run.

Never open a PR from this skill. Discovery only.

The description is the router The agent decides to invoke a skill by reading its description. Write it boring and specific — state plainly when it applies. A clever description does not get matched.

A verifier sub-agent

Location: .claude/agents/<name>.md

---
name: spec-verifier
description: Verify a draft change against project skills and
  existing tests. Read-only.
tools: Read, Grep, Glob, Bash
---

You did not write this code. Assume it is wrong until the tests
say otherwise.

Report only:
1. Does the change satisfy the stated goal?
2. Does it break any rule written in .claude/skills/?
3. Do the tests actually cover the changed lines?

Give findings. Do not praise the work. Do not edit any file.

Rules of thumb

Do	Do not
Put the reason next to the rule	State a bare rule with no history
One skill, one job	One skill that does everything
Give the verifier fewer tools than the maker	Let the verifier edit files
Bundle skills as a plugin to share them	Copy the folder between repos by hand
Spend a strong model on the verifier	Use the same model and prompt for both roles

Sources: Addy Osmani, Agent skills and Loop Engineering; Codex subagents docs.