# Agent Skills Best Practices

> Agent-skill design conventions for focused scope, precise discovery, and progressive disclosure. Use when creating, restructuring, or reviewing `SKILL.md`-based skills.

- Skill: `bastidood/agent-skills-best-practices` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add bastidood/agent-skills-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bastidood/agent-skills-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: BastiDood (https://skillmd.com/u/bastidood)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bastidood/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.](./references/skill-naming.md)
   - [Describe what the skill does and when to invoke it.](./references/trigger-descriptions.md)
2. Keep each skill focused.
   - [Split unrelated triggers or decisions into separate skills.](./references/skill-scope.md)
   - [Separate essential guidance from conditional detail.](./references/context-and-disclosure.md)
   - [Explain when each reference applies.](./references/reference-routing.md)
   - [Contrast approaches and explain why the difference matters.](./references/examples.md)
   - [Keep prose direct and formatting consistent.](./references/prose-and-formatting.md)
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](https://peps.python.org/pep-0723/) and lock them with `uv`.
   - [Make scripts reproducible and usable from read-only installations.](./references/executable-scripts.md)
4. Make guidance usable outside its source project.
   - [Write portable guidance with framework-appropriate examples.](./references/agnostic-references.md)
5. Keep resources portable and in the skill that owns them.
   - [Keep resource paths flat and one hop from the entry point.](./references/directory-structure.md)
   - [Identify external libraries without copying their documentation.](./references/library-sources.md)
   - [Check distribution and licensing rules before bundling assets.](./references/asset-distribution.md)