the BAML agent skill is required but is not installed; run `

Error message

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

What it means

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.

Source

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

}

pub(crate) fn check(project: Option<&Path>) -> anyhow::Result<()> {
    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 {

View on GitHub (pinned to bd85ce9dee)

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.

Example fix

// before (fails in CI)
baml run my_target
// after
baml agent install && baml run my_target
// or opt out
BAML_AGENT_SKILL_CHECK=off baml run my_target

Defensive patterns

Strategy: fallback

Validate before calling

// shell: verify a skill is installed before invoking
for d in .agents/skills .claude/skills; do
  [ -f "$d/baml-core/SKILL.md" ] && found=1
done
[ -n "$found" ] || { echo "run 'baml agent install' first"; exit 1; }

Try / catch

// CI: install the skill as a setup step instead of bypassing
baml agent install || { echo "skill install failed"; exit 1; }
baml run my_target

Prevention

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.

When it happens

Trigger: 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`).

Common situations: 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.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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