skill-best-practices

Validate agent skill metadata and SKILL.md structure against compliance checklists.

Updated May 28, 2026

Search Tags:#discovery #skill authoring #yaml frontmatter #agentskills.io #metadata validation #procedural instructions

Ready to run

npx skills add https://github.com/haryelramalho/skills --skill skill-best-practices-haryelramalho

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: skill-best-practices
Source: https://github.com/haryelramalho/skills/tree/main/skills/curated/skill-best-practices
Command: npx skills add https://github.com/haryelramalho/skills --skill skill-best-practices-haryelramalho

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve?

This Skill helps authors create compliant agent skills that are easy to discover, validate, and activate without guessing at metadata or structure.

Core Features & Use Cases

Metadata validation for name and description rules.
Directory structure guidance for scripts, references, and assets.
Procedural authoring patterns for deterministic, progressive-disclosure skills.
Use case: drafting a new skill, reviewing an existing SKILL.md, or checking helper-path conventions before publishing.

Quick Start

Use the skill-best-practices skill to validate a draft skill directory and refine its SKILL.md until it passes the checklist.

Frequently Asked Questions about skill-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I validate agent skill metadata for agentskills.io compliance?▼

You validate agent skill metadata by applying checklist-based validation to your draft directory, verifying YAML frontmatter rules, directory structure, and helper-path conventions for agentskills.io compliance. This process refines SKILL.md files until all checks pass.

What is the correct directory structure for a compliant agent skill?▼

The correct directory structure for a compliant agent skill includes dedicated folders for scripts, references, and assets. This layout supports deterministic helper references and progressive disclosure patterns required for agentskills.io validation.

How do I write procedural instructions for a new agent skill?▼

You write procedural instructions for an agent skill by using deterministic authoring patterns that enable progressive disclosure. This approach ensures consistent execution without guessing at metadata or structural requirements during skill activation.

What are the YAML frontmatter requirements for publishing an agent skill?▼

YAML frontmatter requirements for publishing an agent skill mandate compliant metadata fields for name and description rules. The validation checklist verifies these fields to ensure proper discovery and activation on agentskills.io.

Can I use skill-best-practices to review an existing SKILL.md file?▼

Yes, you can use skill-best-practices to review an existing SKILL.md file. It validates metadata, checks helper-path conventions, and refines procedural instructions to ensure your current skills meet agentskills.io compliance standards.