When an agent receives a task, skill discovery identifies available skills and provides enough information for the backbone LLM to judge their relevance. Discovery precedes activation, which loads the selected skill’s workflow into the LLM context, and execution of that workflow. section 6.1.3 section 6.6
A skill bundle is a directory containing SKILL.md and optional resources. Its frontmatter describes the skill; the file’s body contains its procedural workflow. A skills catalog discloses skill information to the LLM without initially loading every complete workflow. section 6.6 section 6.1.1
A discovery implementation can follow this flow:
- Resolve the .agents/skills directory for each scope. The project scope uses the current working directory; the user scope uses the home directory. section 6.3.1
- Scan bundle directories and validate each with validate_skill_dir(). A successful validation returns a SkillFrontmatter object and any cosmetic warnings; fatal errors cause the bundle to be skipped. section 6.3.2
- Return discovered skills in a dictionary keyed by name. With the default scope order, project-scoped skills take precedence over user-scoped skills with the same name. section 6.3.2 section 6.3.3
- Store the resulting snapshot in TaskHandler.skills_registry and disclose a catalog to the backbone LLM for relevance decisions. section 6.3.3 section 6.6
Validation is deliberately lenient about cosmetic problems. For example, an overlong name produces a warning, while a missing SKILL.md or invalid frontmatter is fatal. This preserves usable skills without passing invalid bundles downstream. section 6.3.2
Table 6.4 The possible errors and warnings captured during validation.
|
Error / Warning
|
Type
|
Description
|
|
SkillValidationError
|
Fatal
|
Raised when
a skill directory has a general fatal validation issue. Base validation
error.
|
|
MissingSkillMdError
|
Fatal
|
Raised when a skill directory does
not contain a SKILL.md file
|
|
InvalidFrontmatterError
|
Fatal
|
Raised when a SKILL.md file has invalid or unparseable
frontmatter
|
|
EmptySkillBodyError
|
Fatal
|
Raised when a SKILL.md file has no body (main) content
after the frontmatter
|
|
NameMismatchWarning
|
Cosmetic
|
Emitted when the skill name does not
match its parent directory name
|
|
NameTooLongWarning
|
Cosmetic
|
Emitted when the skill name exceeds
64 characters
|
|
All error and warning classes are
found in llm_agents_from_scratch/errors/skill.py
|
||
Compare the fatal errors and cosmetic warnings used during skill-directory validation. section 6.3.2
The Agent Skills standard places discovery at session startup. In a framework without sessions, triggering it when LLMAgent.run() constructs a TaskHandler gives each task a fresh snapshot, so changes between runs are picked up. By contrast, MCP tools are discovered when the agent is created. section 6.3.1 section 6.3.3
Discovering a sequence skill
A project-scoped stop-at-one bundle describes a workflow for computing a Hailstone sequence by repeatedly calling a step-function tool. For a task starting at 8, inspecting TaskHandler.skills_registry shows the skill, its frontmatter, and its project scope. section 6.3.3
The LLM normally decides whether a discovered skill is relevant. User-explicit invocation provides an alternative that enforces use rather than relying on that judgment. section 6.1.3
