skills/

Claude Agent Skills: one subfolder per SKILL.md, loaded on demand.

skills/

Each immediate subfolder of skills/ that contains a SKILL.md file is one skill, following the Claude Agent Skills convention: YAML frontmatter (name, description) followed by a body of freeform instructions.

skills/
└── greeting/
    └── SKILL.md

---
name: greeting
description: How to greet people warmly.
---

Always greet the user warmly and use their name if known.

Naming

The skill's name is its frontmatter name: if present; otherwise it falls back to the folder name (greeting/ with no frontmatter name would be discovered as greeting anyway, but an explicit name: always wins even if it differs from the folder). Two skills resolving to the same name fail validation with a duplicate-name error.

A folder without a SKILL.md inside it is not discovered as a skill at all - it's simply ignored (useful for scratch subfolders, assets kept alongside a skill under a different structure, etc., as long as they don't sit directly under skills/ themselves without a SKILL.md).

How it's wired at runtime

skills/ is copied verbatim into the generated app (same wipe-then-write, dotfile-excluding copy as tools/). The generated config/ColdBox.bx always points bx-ai's own skillsDirectory module setting at /skills:

moduleSettings = {
	bxai : { skillsDirectory : "/skills" }
}