skill-authoring

To create reusable agent skills, you define a SKILL.md file containing a concise name and description in the frontmatter, with operational instructions in the body. This file is scaffolded in the .agents/skills/ directory, enabling instructions and workflows to persist across future sessions.

A SKILL.md file is used to define reusable agent skills by providing a concise name and description in its frontmatter and operational instructions in its body. It acts as a persistent instruction set for future agent sessions to handle specific tasks.

Yes, you can save custom workflows and knowledge by creating user-defined skills in the .agents/skills/ directory. You write the skill instructions as if teaching a fresh agent instance how to handle a task, ensuring the knowledge persists for future sessions.

The .agents/skills/ directory contains editable, user-defined skills that you create and modify, while the ~/.local/skills/ directory stores read-only, platform-managed skills. You scaffold new custom skills directly into the .agents/skills/ directory.

The best way to structure operational instructions in a skill file is to write the body of the SKILL.md as if teaching a fresh agent instance how to handle a task. The frontmatter must include a concise name and description, while the body contains the actual procedures.

No dependencies are required to scaffold a new agent skill. You simply provide the desired skill name in lowercase with hyphens, and the system scaffolds a new skill entry at .agents/skills/SKILLNAME/SKILL.md ready for you to edit.