# Writing for Agents

Write skills, AGENTS.md and CLAUDE.md files that agents follow reliably.

- Repository: https://github.com/mattpocock/skills (309182 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mattpocock/skills --skill writing-for-agents -g -a claude-code -y`
Codex: `npx skills add mattpocock/skills --skill writing-for-agents -g -a codex -y`
Cursor: `npx skills add mattpocock/skills --skill writing-for-agents -g -a cursor -y`
Gemini CLI: `npx skills add mattpocock/skills --skill writing-for-agents -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add mattpocock/skills`

## Description

Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

Reference for writing any document an agent consumes: a skill, an `AGENTS.md` / `CLAUDE.md`, a doc reached by a pointer. The packaging differs; the writing does not: the same levers make each one predictable, since the agent takes the same _process_ every run rather than producing the same output.

When the document you're writing is a skill, read [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) for frontmatter, invocation choice, and router skills.

## Context pointers

A **context pointer** is a reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. A skill's description is one; a line in `AGENTS.md` naming a doc is the same object. The pointer's _wording_, not its target, decides when the agent reaches the material, and how reliably. A must-have target behind a weakly worded pointer is a variance bug: sharpen the wording first, and inline the material only if sharpening fails.

A pointer does two jobs: state what the material is, and list the **branches** that should trigger reaching it (a branch is a distinct case the document handles, so different runs take different paths through it). Every word of an always-loaded pointer costs on every turn, so it earns even harder pruning than the body:

- **Front-load the leading word**: the pointer is where it does its triggering work.
- **One trigger per branch.** Synonyms that rename a single branch are one branch written twice; collapse them and keep only genuinely distinct branches.
- **Cut identity the body already carries.**

## The two loads

Every document and pointer you add spends one of two budgets:

The rest: https://github.com/mattpocock/skills/blob/HEAD/skills/productivity/writing-for-agents/SKILL.md