| name | skill-best-practices |
| description | Authors and structures professional-grade agent skills following the agentskills.io spec. Use when creating new skill directories, drafting procedural instructions, or optimizing metadata for discoverability. Don't use for general documentation, non-agentic library code, or README files. |
| metadata | {"author":"Pedro Nauck","github":"https://github.com/pedronauck","repository":"https://github.com/pedronauck/skills"} |
Skill Authoring Procedure
Follow these steps to generate a skill that adheres to the agentskills.io specification and progressive disclosure principles.
Bundled Path Rule
Resolve bundled paths relative to the directory that contains this SKILL.md. When invoking a helper from another working directory, expand <skill-best-practices-dir> to that directory first so the command is unambiguous.
Step 1: Initialize and Validate Metadata
- Define a unique
name: 1-64 characters, lowercase, numbers, and single hyphens only.
- Draft a
description: Max 1,024 characters, written in the third person, including negative triggers.
- Execute Validation Script (read-only helper): Run the validation script to ensure compliance before proceeding:
python3 <skill-best-practices-dir>/scripts/validate-metadata.py --name "[name]" --description "[description]"
- If the script returns an error, self-correct the metadata based on the
stderr output and re-run until successful.
Step 2: Structure the Directory
- Create the root directory using the validated
name.
- Initialize the following subdirectories:
