Crate craftbag 

Public types, SKILL.md parse, discovery, and activation selector.

DiscoveryOptions::default sets implicit_roots: true so discover walks cwd-to-git .agents / vendor trees and $HOME/.agents / vendor trees. CLI --no-implicit-roots and MCP implicit_roots: false turn that walk off; extra paths and user_skills_dir still load.

SkillMiss peels error_kind, error, and path so a leftover-only host can branch without scraping Display. unknown_skill omits path. A name_collision skip also peels winner_path. Other misses omit it.

List JSON, why JSON, and list XML share SkillSummary (description, invocation flags, argument_hint, when_to_use, triggers, allowed_tools, license, compatibility, metadata). A new field on that type must land in all three wires (skill_summary_json_keys_have_list_xml_siblings). Catalog stays cheap and omits disable_model_invocation (official client-guide). JSON, XML, and TSV still list those rows. format_load_message is the text envelope (License, Compatibility, Metadata, Allowed tools, and host extras when set). format_load_view can print an outline or one heading section of that same SKILL.md body instead of the whole body. It does not dump scripts/ or references/.

validate_path_with_options accepts a SKILL.md file or package directory (joins SKILL.md / skill.md). Success is ValidationReport (no error_kind). A miss is ValidationReport::miss. CLI validate --json and MCP skills_validate share that report.

format_skip_tsv is the skip TSV source (skip\tkind\tpath\tdetail) for CLI list stderr, CLI why stdout, and MCP catalog/xml text. format_list_tsv is default list TSV. format_why_text is CLI why text and MCP skills_why format=text (loaded rows, skip TSV, activation). format_watch_dirs is CLI list --watch-dirs and MCP skills_list format=watch. Do not inline those rows on a new text surface.

Re-exports

pub use discover::CURSOR_VENDOR_DENYLIST;

pub use discover::DiscoveryOptions;

pub use discover::ValidationReport;

pub use discover::discover;

pub use discover::find_skill_by_name;

pub use discover::format_watch_dirs;

pub use discover::validate_path;

pub use discover::validate_path_with_options;

pub use discover::walk_cwd_to_git_root;

pub use discover::watch_dirs;

Structs

ActivationDecision

One activation decision for why.

DiscoveryOptions

Options for multi-root skill discovery.

DiscoveryReport

Result of multi-root skill discovery, including skips for why.

FormatOptions

Host-supplied strings used when formatting catalog and load text.

ProgressiveBudgets

Catalog and auto-body budgets derived from the model context window.

Skill

A parsed skill loaded from a SKILL.md file.

SkillMiss

Host-branchable load / why miss. Display is the one-line text.

SkillOutline

Section keys and token costs for a SKILL.md body.

SkillSection

One heading (or the preamble) plus the text until the next heading.

SkillSectionMeta

One outline row.

SkillSkip

A skill package that discovery found but did not load.

SkillSummary

Loaded skill row for why.

ValidationReport

Result of validating one SKILL.md path.

WhyReport

Doctor report: loaded, skipped, and activation decisions.

Enums

ActivationReason

Why a loaded skill was or was not auto-injected.

Error

Crate-level error. Discovery IO variants land with the discovery slice.

HostTokenField

Which host field produced a refused token. Recorded at construction so miss peel does not grep error prose.

ListFormat

Accepted list --format / MCP skills_list format token.

LoadView

Which SKILL.md body to print after the load envelope.

ParseError

Frontmatter or agentskills field failure.

SkillSource

Where a skill was loaded from.

SkipKind

Why a candidate SKILL.md was not loaded.

Constants

CHARS_PER_TOKEN

Cheap heuristic used by agentskills-core estimate_tokens.

CURSOR_VENDOR_DENYLIST

Cursor vendor-shipped skill names never injected from .cursor roots. Silent in v1 (no skip row).

DEFAULT_ACTIVATE_HINT

Host-neutral wording for how to load one full skill body.

SKILL_BODY_LINE_SOFT_WARN

Soft warn threshold: agentskills recommends keeping SKILL.md under ~500 lines.

SKILL_COMPATIBILITY_MAX_CHARS

agentskills.io: compatibility max length.

SKILL_DESCRIPTION_MAX_CHARS

agentskills.io: description max length.

SKILL_MD_MAX_BYTES

Hard cap on SKILL.md bytes for discover and validate. Prevents unbounded reads.

SKILL_NAME_MAX_CHARS

agentskills.io: name max length.

UNKNOWN_SKILL_KIND

Wire name when load / why matched no skill and no skip.

WHOLE_BODY_CHEAPER_TOKENS

Below this, outline-then-section costs more than the whole body.

Functions

discover

Discover skills for cwd using the host-neutral root matrix.

estimate_tokens

ceil(chars / 4). Empty text is 0.

filter_skills

Filter skills by trigger match and token budget.

find_skill_by_name

Case-insensitive skill lookup by frontmatter name (NFKC).

format_available_skills_xml

Official skills-ref <available_skills> XML inventory for hosts. Includes disable_model_invocation rows (slash palette). The model-facing catalog is format_catalog.

format_catalog

Build a cheap catalog fragment: name + description, plus when_to_use when the author set it.

format_list_tsv

Default list TSV rows (name\tsource\tpath) for CLI list.

format_load_message

User-turn payload that asks the model to follow one skill fully.

format_load_view

Same envelope as format_load_message, with an outline or one section in place of the whole body.

format_package_envelope

Skill package root plus capped listings of scripts/references/assets.

format_skip_tsv

TSV skip rows (skip\tkind\tpath\tdetail) for CLI list stderr, CLI why stdout, and MCP catalog/xml text (stdio has no stderr).

format_watch_dirs

One leftover-safe watch root per line for CLI list --watch-dirs and MCP skills_list format=watch.

format_why_text

Text why rows for CLI why (not --json) and MCP skills_why format=text: loaded\tname\tpath, skip TSV, then activation\tname\treason\tdetail.

normalize_skill_name

NFKC form of a skill name (skills-ref / agentskills Unicode policy).

outline_of

Outline rows plus the cheaper-than-section hint.

parse_list_format

Parse a format token. Surrounding whitespace is ignored.

parse_skill

Parse a SKILL.md file’s content into a Skill.

progressive_budgets

Derive catalog + body budgets from the model context window size.

rank_skills_for_catalog

Rank skills for catalog display: high relevance first, then name.

sanitize_error_token

Echo a host or CLI token on one stderr line.

skill_name_is_ascii_policy

True when name is only a-z0-9-.

skill_name_matches_directory

True when the parent directory name of skill_md matches name.

skill_names_equal

True when two names are the same package after NFKC and case fold.

skill_relevance_score

Relevance score for ranking skills against user text.

skill_section

Body for key, or an error that lists the keys that exist.

split_sections

Split content into flat sections. Parent text stops at the next heading of any level. ATX lines inside a fenced ``` / ~~~ block are not headings.

trigger_matches

Case-insensitive trigger match on word/token boundaries, not substrings.

unknown_list_format

Error text for CLI --format / MCP skills_list format.

unknown_or_skipped_skill

Classify a load miss so hosts can branch without scraping Display.

unknown_or_skipped_skill_message

Error text when load cannot return a skill.

unknown_or_skipped_skill_named

Same as unknown_or_skipped_skill, plus loaded skill names for a single-token typo hint (did you mean review-pr?).

unknown_section_message

One-line miss. key is sanitized like other host-echoed tokens.

validate_path

Validate a SKILL.md path: readable, parse, and name/dir match.

validate_path_with_options

Validate a SKILL.md path or a package directory.

validate_skill_name

Validate agentskills.io name field rules after NFKC.

version

Package version from Cargo.toml.

walk_cwd_to_git_root

Ancestors of cwd through the nearest .git (cwd first).

watch_dirs

Existing directories (and lone extra-path SKILL.md files) a host should watch so hot reload matches discover.

why

Explain loaded vs skipped skills and optional activation decisions.