skill-best-practices

Create agent skill directories following the agentskills.io specification.

567|82|Updated Mar 15, 2026

Search Tags:#developer tools #agent skills #skill authoring #progressive disclosure #metadata validation

Ready to run

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

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill provides a structured process for creating and optimizing agent skills according to the agentskills.io specification, ensuring discoverability and adherence to best practices.

Core Features & Use Cases

Skill Creation Workflow: Guides users through initializing metadata, structuring directories, drafting core logic, and bundling scripts.
Metadata Validation: Emphasizes the use of validation scripts to ensure compliance with naming and description constraints.
Progressive Disclosure: Instructs on moving complex logic to reference files to keep the main SKILL.md concise.
Use Case: When you need to create a new skill for an AI agent, use this skill to ensure it's correctly formatted, validated, and optimized for the agent's understanding.

Quick Start

Use the skill-best-practices skill to create a new skill directory named 'my-new-skill'.

Frequently Asked Questions about skill-best-practices

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

FAQPage Schema

How do I structure and create agent skills for optimal discoverability?▼

To create agent skills with optimal discoverability, structure your project using strict directory conventions, draft concise procedural instructions, and validate metadata against the agentskills.io specification to ensure correct formatting.

What is progressive disclosure in skill authoring and when should I use it?▼

Progressive disclosure in skill authoring is the practice of moving complex logic to reference files to keep the main SKILL.md concise. Use this technique when your agent skill contains extensive procedural instructions that degrade agent performance.

How do I validate metadata and naming conventions for an AI agent skill?▼

You validate metadata and naming conventions for an AI agent skill by running validation scripts that check your project structure against strict description constraints and content length limits, ensuring compliance with the agentskills.io specification.

Do I need Python 3 to author professional agent skills?▼

Yes, you need Python 3 installed in your environment to run the validation scripts that verify your agent skill's directory structure, metadata constraints, and overall compliance with the agentskills.io specification.

What's the best way to organize skill directories and assets for AI agents?▼

The best way to organize skill directories and assets for AI agents is to bundle scripts separately, store detailed references in dedicated files, and maintain a concise core SKILL.md file to optimize the agent's understanding and performance.