skills.rest
yamcodes
yamcodesCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

writing-for-agents

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

1|Updated Aug 24, 2026
Search Tags:#documentation#prompt engineering#agents#claude.md#agents.md#skill writing#context pointers
One-click install
npx skills add https://github.com/yamcodes/the-hat --skill writing-for-agents-yamcodes
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: writing-for-agents
Source: https://github.com/yamcodes/the-hat/tree/main/skills/writing-for-agents
Command: npx skills add https://github.com/yamcodes/the-hat --skill writing-for-agents-yamcodes

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Documents written for AI 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 levers that make agent-consumed 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, with one trigger per branch and front-loaded leading words. - Information Hierarchy: A ladder for placing content as in-file steps, in-file reference, or disclosed reference behind pointers, with progressive disclosure and co-location guidance. - Completion Criteria & Pruning: Techniques for writing checkable, exhaustive step bounds and removing duplication, stale caches, and no-op instructions. - Use Case: When creating a new skill or editing CLAUDE.md, apply these rules to decide what to inline, what to disclose behind pointers, and how to word the description so the agent fires it reliably. ## Quick Start Ask the agent to review your draft skill or AGENTS.md file using the writing-for-agents reference and suggest improvements to its description and structure.

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?▼

A skill description acts as a context pointer: front-load the leading word, state what the material is, and list one trigger per distinct branch the document handles. Cut synonyms and identity the body already carries, since every word costs context on every turn.

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, removing agent discovery so only a human typing its name can invoke it.

When should I split one skill 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 should fire a skill on its own or another skill must reach it. Each split spends context or cognitive load, so the cut must earn it.

Why does my agent skip steps or finish tasks prematurely?▼

Premature completion happens when a step's completion criterion is vague and later steps remain visible, pulling attention toward being done. Sharpen the criterion's bound first; only hide later steps across a real context boundary like a subagent dispatch if the rush persists.

Should I document project conventions in AGENTS.md or rely on config files?▼

Treat the environment (package.json scripts, config files, directory layout) as a source of truth and avoid restating it in documents. Document only what the agent cannot find by looking: unwritten conventions, reasons behind choices, and gotchas no config reveals.

Related Skills

Explore More Software Engineering Skills→
BuilderIOBuilderIO
11

create-instructions

Analyze repository patterns to create project-specific AGENTS.md instructions.

Official
Intermediate
jrgilbertsonjrgilbertson
6

creating-portable-skills

Create, audit, and validate portable Agent Skills packages with structured review and testing.

Community
Advanced
staticalandstaticaland
4

writing-for-agents

Write and structure skills, AGENTS.md, and CLAUDE.md documents for agent consumption.

Community
Intermediate
Sma1lboySma1lboy
136

principle-prove-it-works

Verify completed work by directly inspecting the real artifact instead of proxies or self-reports.

Community
Basic