writing-for-agents

Guides writing skills, AGENTS.md, and CLAUDE.md documents that agents follow predictably.

Updated Mar 27, 2026
One-click install
npx skills add https://github.com/gmackie/agent-skills --skill writing-for-agents-gmackie
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: writing-for-agents
Source: https://github.com/gmackie/agent-skills/tree/main/skills/writing-for-agents
Command: npx skills add https://github.com/gmackie/agent-skills --skill writing-for-agents-gmackie

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Documents written for agents often fail to produce consistent behavior: weak descriptions never trigger, bloated files bury key steps, and vague completion criteria let agents stop early. This Skill provides a disciplined framework for writing any agent-consumed document so the agent follows a predictable process on every run. ## Core Features & Use Cases - Context pointer design: Write descriptions and AGENTS.md lines with front-loaded leading words and one trigger per branch so material is reached reliably. - Information hierarchy and progressive disclosure: Place steps and reference on the right tier, disclose branch-specific material behind pointers, and co-locate related rules to fight sprawl. - Completion criteria and splitting: Define clear, demanding done-conditions to prevent premature completion, and split documents by sequence or invocation when the cut earns it. - Use Case: When authoring a new skill or editing CLAUDE.md, apply the pruning rules (single source of truth, no-op detection, relevance checks) to keep the document short, live, and behavior-changing. ## Quick Start Ask the agent to review your draft SKILL.md or AGENTS.md using the writing-for-agents guidance and tighten its description, steps, and completion criteria.

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 word, list one trigger per distinct branch the document handles, and cut anything the body already states. Every word stays loaded on every turn, so prune it harder than the body.

How to structure AGENTS.md or CLAUDE.md for agents?▼

Order steps as the primary tier, keep on-demand reference as flat peers, and disclose branch-specific material into separate files behind pointers. Co-locate each concept's definition, rules, and caveats under one heading instead of scattering them.

When should a skill be model-invoked vs user-invoked?▼

Choose model-invocation when the agent or another skill must reach it autonomously, accepting the permanent context load of an always-loaded description. Set disable-model-invocation: true for skills only ever fired by hand, paying zero context load.

Why does my agent stop a task before finishing?▼

Premature completion comes from vague completion criteria combined with visible post-completion steps pulling attention forward. Sharpen the step's done-bound first; only split the sequence across a real context boundary if the bound stays fuzzy and rushing persists.

What are the limitations of progressive disclosure in agent docs?▼

Pushing too much material behind pointers hides content the agent actually needs, while pushing too little bloats the top of the file. Inline what every branch needs and disclose only what some branches reach; user-invoked skills cannot share reference with each other.