# Skills agent guide
`mod.rs` discovers skill descriptors; reading a selected skill or reference belongs to `../tools/skill.rs`.
## Discovery contracts
- Discover `SKILL.md` under a skill directory or one grouping directory below it. This is a shallow scan, not arbitrary recursive discovery.
- Collision priority is repository `.agents/skills`, configured additional roots, `$MC_HOME/skills`, then legacy `~/.agents/skills`.
- Additional roots must be absolute. They are processed in listed order, with later discoveries replacing earlier entries of the same name.
- Sort discovered paths and retain diagnostics for duplicate names within one root. `BTreeMap` keeps the resulting skill list deterministic.
- The skill name comes from the containing directory, not frontmatter `name`.
- Reject non-regular descriptor files, including symlinked `SKILL.md`; directory traversal does not recurse through symlink entries.
- Descriptor reads have a 1 MiB cap. Keep discovery failures as per-path diagnostics rather than aborting all roots.
## Metadata and enablement
- Frontmatter is a flat key/value parser, not a general YAML implementation. Preserve CRLF handling, scalar quoting, and malformed-marker diagnostics.
- `filter_enabled_skills` removes names in the disabled set; discovery is not an explicit opt-in list.
- Keep discovery separate from reference loading and execution. Tool-level reference containment remains enforced even after a descriptor has been discovered.
Existing tests in `mod.rs` cover root precedence, shallow discovery, frontmatter, duplicates, filtering, and unsafe sources; extend those when changing these contracts.