{"record":{"id":"4f5560d6c8c67ad1","repo":"BoundaryML/baml","slug":"the-baml-agent-skill-is-required-but-is-not-installed-run","errorCode":null,"errorMessage":"the BAML agent skill is required but is not installed; run `baml agent install`, restart the agent, then retry; set BAML_AGENT_SKILL_CHECK=off to bypass this check","messagePattern":"the BAML agent skill is required but is not installed; 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":58,"sourceCode":"}\n\npub(crate) fn check(project: Option<&Path>) -> anyhow::Result<()> {\n    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 {","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/baml_language/crates/baml_cli/src/skill_check.rs#L40-L76","documentation":"Under the default `Require` agent-skill-check policy, the CLI verified that the BAML agent skill (a SKILL.md under `.agents/skills/` or `.claude/skills/`, searched upward from the project root to $HOME) is not installed, and hard-fails. The check keeps the agent-facing skill instructions in sync with the toolchain; this error means the tool refuses to proceed until the skill is installed.","triggerScenarios":"Any CLI invocation subject to the check when no SKILL.md exists in `.agents/skills/` or `.claude/skills/` at the project root or any ancestor up to $HOME, or when no project root can be found; policy is `Require` (not `Warn` or `Off`).","commonSituations":"Fresh checkout or CI container where `baml agent install` was never run; a project that omits the skills directory entirely; running outside any recognized project; upgrading tooling on a machine where the skill setup step was skipped.","solutions":["Run `baml agent install`, restart the agent, then retry the command.","If the skill is intentionally not wanted, set `BAML_AGENT_SKILL_CHECK=off` to bypass the check.","Switch the policy to `Warn` in your output/agent configuration if you want warnings instead of hard failures.","Ensure you run inside the project root (or a subdirectory of it) so the installed skill is discovered."],"exampleFix":"// before (fails in CI)\nbaml run my_target\n// after\nbaml agent install && baml run my_target\n// or opt out\nBAML_AGENT_SKILL_CHECK=off baml run my_target","handlingStrategy":"fallback","validationCode":"// shell: verify a skill is installed before invoking\nfor d in .agents/skills .claude/skills; do\n  [ -f \"$d/baml-core/SKILL.md\" ] && found=1\ndone\n[ -n \"$found\" ] || { echo \"run 'baml agent install' first\"; exit 1; }","typeGuard":null,"tryCatchPattern":"// CI: install the skill as a setup step instead of bypassing\nbaml agent install || { echo \"skill install failed\"; exit 1; }\nbaml run my_target","preventionTips":["Add `baml agent install` to project setup scripts and CI bootstrap.","Commit the installed skill directory so fresh checkouts work.","Only use BAML_AGENT_SKILL_CHECK=off deliberately and temporarily."],"tags":["cli","agent","skill","setup","baml"],"backgroundTag":"missing-dependency","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"}