nikivdev/code · error

Commit blocked by required skill gate

Error message

Commit blocked by required skill gate

What it means

The library enforces a 'required skill gate' before commits: it builds a report of policy/version failures and, when the policy mode is "block", any failure aborts the commit. In "warn" mode the same failures only print a warning. This lets teams mandate project-defined skills/checks as a precondition to committing.

Source

Thrown at src/commit.rs:3135

            }
        } else if let Some(version) = skills::read_skill_version_at(repo_root, skill_name)? {
            report.loaded_versions.insert(skill_name.clone(), version);
        }
    }

    report.pass = report.missing_skills.is_empty() && report.version_failures.is_empty();
    if !report.pass {
        for missing in &report.missing_skills {
            eprintln!(
                "  skills: required skill '{}' is missing in .ai/skills/",
                missing
            );
        }
        for failure in &report.version_failures {
            eprintln!("  skills: {}", failure);
        }
        if policy.mode == "block" {
            bail!("Commit blocked by required skill gate");
        }
        eprintln!("  skills: warning only (mode=warn)");
    }

    Ok(report)
}

fn build_required_skills_prompt_context(
    repo_root: &Path,
    skill_report: &SkillGateReport,
) -> String {
    if skill_report.required_skills.is_empty() {
        return String::new();
    }

    let mut sections = Vec::new();
    for skill_name in &skill_report.required_skills {
        if let Ok(Some(content)) = skills::read_skill_content_at(repo_root, skill_name) {

View on GitHub (pinned to a747e741ae)

Solutions

1. Read the printed `skills: <failure>` lines and install/upgrade the listed required skills to the required versions.
2. Run the project's setup script to provision missing skills.
3. Temporarily set the gate policy mode to "warn" in project config if the team permits (not recommended for CI-shared config).
4. Use any documented gate override (e.g. gate_overrides) only if policy allows bypassing.

Example fix

// before (project config)
{ "required_skills": [{ "name": "review", "version": "2.0" }], "mode": "block" }
// after installing the skill
$ skills install review@2.0
$ commit ... // passes gate

// Check required skills are present at required versions before committing
// (using the project's skills CLI)
// $ skills check --required  # exits non-zero if version_failures exist

if let Err(e) = commit_flow() {
    if e.to_string().contains("Commit blocked by required skill gate") {
        eprintln!("install/upgrade the skills listed in the gate output, then retry");
    } else { return Err(e.into()); }
}

When it happens

Trigger: Committing while the skill gate report contains version_failures (or other failures) and the configured policy mode equals "block" (e.g. from project config specifying required skills with mode=block).

Common situations: Cloning a project whose config requires skills you have not installed or at versions you do not satisfy; forgetting to run the repo's setup/bootstrap; locally downgrading a required tool; misconfigured skill paths in config.

Related errors

• Commit blocked by invariant gate ({} finding(s))
• Commit blocked by testing gate
• jj git export retry loop should always return
• Lin.app is not running
• No branches available to search

AI-assisted analysis of nikivdev/code@a747e741ae (2026-09-01). Data as JSON: /api/errors/a8d8a6e2ff98c9ec. Report an issue: GitHub.