writing-for-agents

Guides writing skills, AGENTS.md, and CLAUDE.md documents for agent consumption.

1|Updated Feb 2, 2026
One-click install
npx skills add https://github.com/rockcookies/skills --skill writing-for-agents-rockcookies
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: writing-for-agents
Source: https://github.com/rockcookies/skills/tree/main/skills/mattpocock/writing-for-agents
Command: npx skills add https://github.com/rockcookies/skills --skill writing-for-agents-rockcookies

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Documents written for agents often fail unpredictably: weak descriptions never trigger, bloated files bury key steps, and vague completion criteria let agents stop early. This Skill provides a reference of writing principles that make agent-facing documents behave consistently across runs. ## Core Features & Use Cases - Context pointer design: Rules for writing skill descriptions and AGENTS.md lines that reliably trigger the right material at the right branch. - Information hierarchy: A ladder model (in-file steps, in-file reference, disclosed reference) for deciding what to inline versus push behind a pointer. - Completion criteria and splitting: Guidance on sharpening step boundaries, preventing premature completion, and splitting documents by sequence or invocation. - Use Case: When authoring a new skill, apply the leading-word, pruning, and negation rules to cut token load while making the agent's behavior more predictable. ## Quick Start Ask the agent to review your draft SKILL.md or AGENTS.md using the writing-for-agents principles and suggest concrete edits.

Frequently Asked Questions about writing-for-agents

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a good skill description for an AI agent?▼

Write the description as a context pointer: front-load the leading trigger word and list one trigger per distinct branch the document handles. Cut synonyms and identity the body already carries, since every word of an always-loaded description costs context on every turn.

How should I structure a SKILL.md or AGENTS.md file?▼

Order content along an information hierarchy: in-file steps first, in-file reference consulted on demand, then disclosed reference pushed to separate files behind pointers. Inline what every branch needs and disclose what only some branches reach.

What is the difference between model-invoked and user-invoked skills?▼

A model-invoked skill keeps a description so the agent and other skills can fire it autonomously, paying permanent context load. A user-invoked skill sets disable-model-invocation: true, so only a human typing its name can trigger it, costing zero context load.

When should I split one agent document into two?▼

Split by sequence when visible later steps tempt the agent to rush the current one, and split by invocation when a distinct trigger word deserves its own model-invoked skill. Each split spends context or cognitive load, so the cut must earn it.

Why do agents ignore instructions written as negations?▼

Negations activate the forbidden concept in context, making it more available rather than less. State the positive target behavior instead, reserving prohibitions for hard guardrails paired with the positive instruction.