Agent Skills Best Practices

Treat agent skills as opinionated context engineering, not as mirrors of documentation that an agent can fetch elsewhere. A skill earns its context cost by preserving distinctive judgment, repeatable procedure, or peripheral knowledge that materially changes how an agent works.

Keep the governing model and the minimum explainer needed to understand a skill in SKILL.md. Inline content that every invocation needs. Reserve progressive disclosure for conditional or detail-oriented guidance, and route to that guidance with concise prose that explains why it matters.

References

Read as many linked references as are relevant to the authoring or review task.