mgechev/skills-best-practices

What it solves

This project provides a set of professional-grade best practices for creating "agent skills"—modular, structured instructions and tools that allow AI agents to perform complex, deterministic tasks without consuming excessive tokens or hallucinating steps.

How it works

It defines a standardized directory structure and design patterns for skills, focusing on reducing the LLM's context window load through "progressive disclosure."

• Structure: A skill consists of a SKILL.md (the brain), a scripts/ folder for deterministic code, references/ for supplementary context, and assets/ for templates.
• Discoverability: It emphasizes optimizing YAML frontmatter (name and description) so agents can accurately trigger the correct skill.
• Instruction Style: It advocates for third-person imperative commands and step-by-step numbering over prose to ensure the agent follows a strict chronological sequence.
• Deterministic Offloading: Fragile or repetitive tasks are moved from the LLM's prompt into tested scripts (Python, Bash, Node) to prevent errors.
• Validation: It provides a framework for using LLMs to validate discovery, logic, and edge cases before deployment.

Who it’s for

Developers building AI agents and tool-use capabilities who want to standardize how they define capabilities and optimize for reliability and token efficiency.

Highlights

• Progressive Disclosure: Keeps the main instruction file lean (<500 lines) and directs agents to load external files only when needed.
• Detailed Validation Guide: Includes specific prompts to test if an agent will correctly trigger a skill and simulate its execution to find logic gaps.
• Deterministic Scripts: Encourages bundling small CLIs to handle complex parsing or boilerplate code.
• Router Skills: Supports skill composition, allowing one skill to act as a router to other sub-skills.