skills-best-practices
Write professional-grade skills for agents, validate them using LLMs, and maintain a lean context window.
This repository provides a structured methodology for authoring high-quality agent skills that work with LLM-based assistants. It defines best practices for organizing skill directories (SKILL.md, scripts, references, assets), optimizing frontmatter for agent discoverability, and maintaining lean context windows through progressive disclosure. The guide includes validation techniques using LLMs themselves to test discovery logic, execution flow, edge cases, and architectural soundness. Developers use these patterns to create professional-grade, composable skills that agents can reliably trigger and execute.
Key Features
Use Cases
- 01Building framework-specific skills (React, Angular, Vue) with proper tooling integration and build configurations
- 02Creating migration skills that transform codebases between architectures or bundlers with deterministic scripts
- 03Designing API integration skills with schemas and authentication flows stored in references/
- 04Structuring testing and validation skills with templates in assets/ and execution scripts
- 05Composing multi-step deployment skills with conditional logic for different build targets
- 06Preventing skill regression by validating frontmatter triggers and execution paths with LLMs before release
Related Skills
View moresuperpowers
An agentic skills framework & software development methodology that works.
skills
Skills for Real Engineers. Straight from my .agents directory.
skills
Public repository for Agent Skills
ponytail
Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.
skills-best-practices — FAQ
What is skills-best-practices and what does it do?+
It is a comprehensive guide and methodology for creating professional-grade agent skills following the agentskills.io specification. The repository documents directory structure standards, frontmatter optimization, progressive disclosure patterns, and LLM-based validation techniques to ensure skills are discoverable and execute reliably.
How do I use this guide to create my own agent skills?+
Follow the prescribed directory structure (SKILL.md with scripts/, references/, assets/ subdirectories), write trigger-optimized frontmatter with specific naming rules, keep your main file under 500 lines, and validate using the four-phase LLM testing workflow (discovery, logic, edge cases, architecture). Reference the specific patterns and examples provided for file organization and instruction formatting.
Which AI clients and agents work with skills built using these practices?+
Skills following the agentskills.io specification work with Claude and other LLM-based assistants that support the skill loading mechanism described in Claude's official documentation. The guide references Claude's platform documentation as the comprehensive source for agent skill implementation.
Do I need any API keys or special tools to implement these practices?+
No special API keys are required to follow the structural guidelines. However, the validation workflow recommends using LLMs (like Claude) to test your skill's discovery logic and execution flow, and optionally the skillgrade tool for regression testing.
Is this guide free to use?+
Yes, the repository is open-source and available on GitHub under mgechev's account. The practices and patterns documented are freely available for developers building agent skills.
What is the difference between SKILL.md and the references/ directory?+
SKILL.md acts as the "brain" containing high-level navigation and primary procedures (kept under 500 lines), while references/ stores supplementary context like API documentation, schemas, and cheatsheets that are loaded just-in-time when the agent explicitly reads them. This progressive disclosure pattern prevents context window bloat.
How do I install skills-best-practices?+
Open the source repository on GitHub and follow its README. skills-best-practices is a skill — MCP Agents Market links you directly to the official repo.
Is skills-best-practices free?+
skills-best-practices is an open-source project hosted on GitHub. Check the repository for its license and any usage requirements.