agent-skills-best-practices

Agent Skills Best Practices

Use skills for decisions, procedures, and knowledge that change how the agent works. Do not repeat documentation it can look up.

Keep essential guidance in SKILL.md. Put conditional detail in references and explain when to read each.

Show, don't tell: pair contrasting examples with a short explanation.

References

1. Make the skill easy to find and invoke.
   • Name the procedure or subject the skill covers.
   • Describe what the skill does and when to invoke it.
2. Keep each skill focused.
   • Split unrelated triggers or decisions into separate skills.
   • Separate essential guidance from conditional detail.
   • Explain when each reference applies.
   • Contrast approaches and explain why the difference matters.
   • Keep prose direct and formatting consistent.
3. Use scripts for deterministic work and models for judgment. Prefer existing tools and standard libraries. Declare required third-party Python dependencies with PEP 723 and lock them with uv.
   • Make scripts reproducible and usable from read-only installations.
4. Make guidance usable outside its source project.
   • Write portable guidance with framework-appropriate examples.
5. Keep resources portable and in the skill that owns them.
   • Keep resource paths flat and one hop from the entry point.
   • Identify external libraries without copying their documentation.
   • Check distribution and licensing rules before bundling assets.