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.

BastiDood Updated Sep 17, 2026

Product & Planning

Install

Press C to copy

$ npx skillmds@latest add bastidood/agent-skills-best-practices

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

＋ Add to collection

README badge

[![SkillMD](https://skillmd.com/badge/bastidood/agent-skills-best-practices.svg)](https://skillmd.com/skills/bastidood/agent-skills-best-practices)

Trust & safety

Audits pending

Not yet audited · commit 1a9b81d

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

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

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.
Keep each skill focused.
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.
Make guidance usable outside its source project.
- Write portable guidance with framework-appropriate examples.
Keep resources portable and in the skill that owns them.

---name: agent-skills-best-practicesdescription: Agent-skill design conventions for focused scope, precise discovery, and progressive disclosure. Use when creating, restructuring, or reviewing `SKILL.md`-based skills.---# Agent Skills Best PracticesUse 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.## References1. 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)

BastiDood/skills/tree/main/plugins/meta/skills/agent-skills-best-practices commit 1a9b81d0aa

Frequently asked questions

npx skillmds@latest add bastidood/agent-skills-best-practices