Instruction file imported from GodSpeedAI/VibesPro (
.github/instructions/skills.instructions.md). Copyright stays with the author.
Skill Authoring Instructions
Agent skills encapsulate specialised capabilities that can be composed together. To develop a new skill:
-
Follow the Agent Skills specification. Each skill must reside in its own directory containing a
SKILL.mdfile, optionalscripts/,references/andassets/folders. TheSKILL.mdmust include YAML front matter with anameanddescriptionand may include optional fields such aslicense,compatibilityorallowed-tools. -
Leverage progressive disclosure. Keep the
SKILL.mdbody concise (ideally under 500 lines) and defer extensive documentation, examples or scripts to thereferences/folder. Only load these resources when explicitly required to save context tokens【213465190888775†L602-L625】. -
Define IO explicitly. In the
metadatasection, list what files, concepts and tools the skill requires (inputs) and what actions it performs or artifacts it produces (outputs). Declare any hard dependencies independsOnand soft links inrelated. Accurate IO declarations enable deterministic routing. -
Write actionable instructions. The body of
SKILL.mdshould provide clear, step‑by‑step guidance to the agent on how to use the skill. Include criteria for success, potential edge cases and how to handle errors. -
Avoid hidden side effects. Skills should not mutate state outside of their declared outputs. For example, if a skill writes files, ensure it lists a corresponding action in
outputsand that a validation task will run afterwards. -
Document references and scripts. Any supporting files (e.g. example templates, configuration snippets or Python scripts) belong in the
references/orscripts/subdirectories. Refer to them in theSKILL.mdbody so the agent knows when to load them.
Following these principles will yield modular, reusable skills that enhance the overall capabilities of your AI agent ecosystem without causing context bloat or technical debt.