Writing Agent Skills: Don't Stuff the Context First

Anthropic wrote a set of best practices for Agent Skills in its documentation. Bilgin Ibryam condensed them into eight rules and one summary sentence: small entry point, precise discovery, progressive detail, explicit verification.

Agent Skills can be understood as a work instruction manual for the model: the entry point explains what the skill does and when to use it, while details and resources are loaded on demand. The documentation is here, and Bilgin Ibryam's tweet is here.

The eight rules are not complicated; the hard part is not doing the opposite when writing.

1. Be concise and clear. Assume the model is capable; add only the necessary context. It is easy for Skill writing to slide into a prompt contest, piling on background and adjectives until the entry point is long and hard to discover.
2. Adjust the degree of freedom. Give stricter instructions for high-freedom tasks and the opposite for low-freedom tasks. Rules should match how open the task is.
3. Precise discovery. State clearly what the skill does and when to use it. Don't turn the name and description into slogans; the model relies on them to decide whether to load the skill.
4. Progressive disclosure. Keep the entry point small and load detailed information on demand. This is the most easily overlooked rule. Part of a Skill's value lies in context management, not in stuffing everything in at once.
5. Encode workflows. Break complex tasks into explicit steps. The steps must be executable; don't write them as a list of principles.
6. Closed loop. Verification beats hoping the model is correct. Leave checkpoints in the process; this is more useful than adding 'please make sure it is correct' at the end.
7. Show, don't over-explain. Concrete examples are easier to understand than lengthy explanations. Examples should closely match real inputs and outputs.
8. Evaluate and iterate. Build evaluations first, then test the target model's actual behavior. Without evaluation, the rules are just feelings.

The sentence at the bottom of the image captures the eight rules precisely: small entry point, precise discovery, progressive detail, explicit verification. For ordinary users, a Skill is like a short table of contents plus an expandable manual. For developers, the key is to write process steps and acceptance criteria into it. When writing a Skill, don't treat the model like an intern and spoon-feed it every step. A more reasonable approach is to design a loading path so that the model gets the information it needs when it needs it. This judgment sounds like common sense, but when it lands in documentation it often turns into the opposite practice.

If you are writing an Agent Skill, check rules 4 and 6 first, then go back to the other six.