{"record":{"id":"aa7e27b3a9e39252","repo":"BoundaryML/baml","slug":"the-installed-baml-agent-skill-does-not-match-this-toolchain","errorCode":null,"errorMessage":"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","messagePattern":"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","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"baml_language/crates/baml_cli/src/skill_check.rs","lineNumber":61,"sourceCode":"    let policy = crate::output::policy().agent_skill_check;\n    if policy == AgentSkillCheckPolicy::Off {\n        return Ok(());\n    }\n\n    let status = project_skill_status(project)?;\n    match (policy, status) {\n        (_, SkillStatus::Current) => Ok(()),\n        (AgentSkillCheckPolicy::Warn, status) => {\n            if let Some(message) = skill_warning_message(status) {\n                crate::reporter::print_warning(format_args!(\"{message}\"));\n            }\n            Ok(())\n        }\n        (AgentSkillCheckPolicy::Require, SkillStatus::Missing) => {\n            anyhow::bail!(SKILL_MISSING_ERROR)\n        }\n        (AgentSkillCheckPolicy::Require, SkillStatus::Outdated) => {\n            anyhow::bail!(SKILL_OUTDATED_ERROR)\n        }\n        (AgentSkillCheckPolicy::Off, _) => Ok(()),\n    }\n}\n\nfn skill_warning_message(status: SkillStatus) -> Option<&'static str> {\n    match status {\n        SkillStatus::Missing => Some(SKILL_MISSING_WARNING),\n        SkillStatus::Outdated => Some(SKILL_OUTDATED_WARNING),\n        SkillStatus::Current => None,\n    }\n}\n\nfn project_skill_status(project: Option<&Path>) -> anyhow::Result<SkillStatus> {\n    let mut dir = match project {\n        Some(project) => match crate::project_load::find_project_root_from(Some(project))? {\n            Some(root) => root,\n            None => return Ok(SkillStatus::Missing),","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/baml_language/crates/baml_cli/src/skill_check.rs#L43-L79","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before (after upgrading baml)\nbaml run my_target  # Error: skill does not match this toolchain\n// after\nbaml agent install && baml run my_target","handlingStrategy":"retry","validationCode":"// shell: compare skill frontmatter version against toolchain\nv=$(grep -m1 baml-toolchain-version .agents/skills/*/SKILL.md | sed 's/.*: *//; s/\"//g')\n[ \"$v\" = \"$(baml --version)\" ] || baml agent install","typeGuard":null,"tryCatchPattern":"if ! baml run my_target 2>err.log; then\n  grep -q 'does not match this toolchain' err.log && { baml agent install; baml run my_target; } || { cat err.log; exit 1; }\nfi","preventionTips":["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."],"tags":["cli","agent","skill","version-mismatch","baml"],"backgroundTag":"version-mismatch","analyzedSha":"bd85ce9dee1463ff04d27efd20531013a4ff46c1","analyzedAt":"2026-09-12T03:38:25.718Z","contentChangedAt":"2026-09-12T03:38:25.718Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}