liveBook · Manning

Skill discovery

As explained in Build a Multi-Agent System (from Scratch)

Skill discovery is the process by which an LLM agent identifies available skills and determines whether one is relevant to a task.

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

How Build a Multi-Agent System (from Scratch) covers it

How deep it goes
Works through scope paths, bundle validation, registry construction, collision precedence, and task-start wiring; defers activation implementation.
Examples
Demonstrates discovery of a project-scoped Hailstone sequence skill and inspection of its registry entry, frontmatter, and scope.
What you can do after
Build it from scratch: implement skill-directory scanning, validation, and task-start registry population in an LLM agent.
How it connects
Connects progressive disclosure, LLM reasoning, skill activation, and execution, contrasting discovery timing with MCP tools.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Build a Multi-Agent System (from Scratch). The section links point to the parts of the book it draws on.