writing-for-agents

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

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Documents written for agents often produce inconsistent behavior: agents skip steps, finish prematurely, or ignore reference material. This Skill provides a reference framework for writing any document an agent consumes so the agent follows the same process every run. ## Core Features & Use Cases - Context pointer design: Rules for writing descriptions and pointer lines that reliably trigger the agent to reach out-of-context material, with one trigger per branch. - Information hierarchy and progressive disclosure: A ladder for placing steps, in-file reference, and disclosed reference so documents stay legible without hiding needed material. - Completion criteria and splitting: Guidance on writing checkable, exhaustive completion criteria and deciding when to split documents by sequence or invocation. - Use Case: When authoring a new skill or editing an AGENTS.md file, apply the pruning, leading-word, and negation rules to remove no-op sentences and sharpen the agent's behavior. ## Quick Start Ask the agent to review your SKILL.md or AGENTS.md draft using the writing-for-agents reference and rewrite weak pointers and vague 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 skill description that agents trigger reliably?

Write the description as a context pointer: front-load the leading word, state what the material is, and list one trigger per distinct branch. Cut synonyms that rename a single branch and remove identity the body already carries, since every word of an always-loaded pointer costs context on every turn.

How do I structure an AGENTS.md or skill file for agents?

Organize content on the information hierarchy: in-file steps first, in-file reference second, and disclosed reference behind pointers last. Inline what every branch needs and push behind a pointer what only some branches reach, keeping each concept's definition, rules, and caveats co-located under one heading.

When should I split one skill into two skills?

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

Should a skill be model-invoked or user-invoked?

Choose model-invoked when the agent or another skill must reach it autonomously, accepting the permanent context load of an always-loaded description. Choose user-invoked with disable-model-invocation when it only ever fires by hand, paying zero context load but requiring the human to remember it exists.

Why do agents ignore instructions written as negations?

Negation drags the forbidden behavior into context and makes it more available, since the strongly-activated concept overruns the weak negation modifier. State the positive target behavior instead, reserving prohibitions for hard guardrails that cannot be phrased positively.

What are the limitations of progressive disclosure in agent documents?

Pushing too much material behind pointers hides content the agent actually needs, while pushing too little bloats the top of the document. Disclosure also only works across a real context boundary such as a hand-off or subagent dispatch; an inline call leaves later steps in context.