the installed BAML agent skill does not match this toolchain

Error message

the installed BAML agent skill does not match this toolchain; run `baml agent install`, restart the agent, then retry; set BAML_AGENT_SKILL_CHECK=off to bypass this check

What it means

Under the `Require` agent-skill-check policy, the CLI found an installed BAML agent skill whose SKILL.md frontmatter `baml-toolchain-version` does not match the current toolchain version (or the frontmatter is unparseable/unreadable), and hard-fails. This guarantees each toolchain version ships with its matching skill instructions.

Source

Thrown at baml_language/crates/baml_cli/src/skill_check.rs:61

    let policy = crate::output::policy().agent_skill_check;
    if policy == AgentSkillCheckPolicy::Off {
        return Ok(());
    }

    let status = project_skill_status(project)?;
    match (policy, status) {
        (_, SkillStatus::Current) => Ok(()),
        (AgentSkillCheckPolicy::Warn, status) => {
            if let Some(message) = skill_warning_message(status) {
                crate::reporter::print_warning(format_args!("{message}"));
            }
            Ok(())
        }
        (AgentSkillCheckPolicy::Require, SkillStatus::Missing) => {
            anyhow::bail!(SKILL_MISSING_ERROR)
        }
        (AgentSkillCheckPolicy::Require, SkillStatus::Outdated) => {
            anyhow::bail!(SKILL_OUTDATED_ERROR)
        }
        (AgentSkillCheckPolicy::Off, _) => Ok(()),
    }
}

fn skill_warning_message(status: SkillStatus) -> Option<&'static str> {
    match status {
        SkillStatus::Missing => Some(SKILL_MISSING_WARNING),
        SkillStatus::Outdated => Some(SKILL_OUTDATED_WARNING),
        SkillStatus::Current => None,
    }
}

fn project_skill_status(project: Option<&Path>) -> anyhow::Result<SkillStatus> {
    let mut dir = match project {
        Some(project) => match crate::project_load::find_project_root_from(Some(project))? {
            Some(root) => root,
            None => return Ok(SkillStatus::Missing),

View on GitHub (pinned to bd85ce9dee)

Solutions

Run `baml agent install` to reinstall the skill matching this toolchain, restart the agent, then retry.
Set `BAML_AGENT_SKILL_CHECK=off` to bypass the version check.
Commit the refreshed SKILL.md after upgrading so teammates/CI get the matching version.
Remove stale skill directories (e.g. an old `.claude/skills/...` in a parent dir) that shadow the current one.

Example fix

// before (after upgrading baml)
baml run my_target  # Error: skill does not match this toolchain
// after
baml agent install && baml run my_target

Defensive patterns

Strategy: retry

Validate before calling

// shell: compare skill frontmatter version against toolchain
v=$(grep -m1 baml-toolchain-version .agents/skills/*/SKILL.md | sed 's/.*: *//; s/"//g')
[ "$v" = "$(baml --version)" ] || baml agent install

Try / catch

if ! baml run my_target 2>err.log; then
  grep -q 'does not match this toolchain' err.log && { baml agent install; baml run my_target; } || { cat err.log; exit 1; }
fi

Prevention

Re-run `baml agent install` whenever the baml CLI is upgraded.
Commit refreshed SKILL.md files in the same PR as toolchain bumps.
Watch for the 'Warn' variant warning and refresh promptly.

When it happens

Trigger: A SKILL.md exists under `.agents/skills/` or `.claude/skills/` (or an ancestor directory up to $HOME), but its `baml-toolchain-version` frontmatter differs from `baml_version::CANONICAL_VERSION`, or the frontmatter fails to parse or the file can't be read (non-NotFound IO error).

Common situations: Upgrading the baml CLI without re-running `baml agent install`; a stale skill committed to the repo from an older toolchain; a hand-edited or corrupted SKILL.md frontmatter; multiple projects with skills at different versions on the same path chain.

Related errors

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/aa7e27b3a9e39252. Report an issue: GitHub.