crewAIInc/crewAI · error · SystemExit

Failed to publish skill. Local changes need to be resolved b

Error message

Failed to publish skill.
Local changes need to be resolved before publishing. Please do the following:
* Commit your changes.
* Push to sync with the remote.
* Pull the latest changes from the remote.

Once your repository is up-to-date, retry publishing the skill (or pass --force to skip this check).

What it means

`repository.is_synced()` returned False after a successful fetch, meaning local branch state diverges from the remote: uncommitted changes, unpushed commits, or the remote is ahead. The CLI refuses to publish from a dirty repo so that published skill versions always map to a traceable git state, unless `--force` is passed.

Source

Thrown at lib/cli/src/crewai_cli/skills/main.py:229

                    # against the actual remote, not stale local state.
                    repository.fetch()
                except ValueError as exc:
                    console.print(
                        f"[red]Unable to validate git state: {exc}\n"
                        "Fix the issue or pass --force to skip this check.[/red]"
                    )
                    raise SystemExit(1) from exc
            if repository is not None and not repository.is_synced():
                console.print(
                    "[bold red]Failed to publish skill.[/bold red]\n"
                    "Local changes need to be resolved before publishing. Please do the following:\n"
                    "* [bold]Commit[/bold] your changes.\n"
                    "* [bold]Push[/bold] to sync with the remote.\n"
                    "* [bold]Pull[/bold] the latest changes from the remote.\n"
                    "\nOnce your repository is up-to-date, retry publishing the skill "
                    "(or pass --force to skip this check)."
                )
                raise SystemExit(1)

        try:
            frontmatter = self._parse_frontmatter(skill_md.read_text(encoding="utf-8"))
        except ValueError as exc:
            console.print(f"[red]Failed to parse SKILL.md frontmatter: {exc}[/red]")
            raise SystemExit(1) from exc

        name = frontmatter.get("name")
        raw_metadata = frontmatter.get("metadata")
        version = (
            raw_metadata.get("version") if isinstance(raw_metadata, dict) else None
        )
        description = frontmatter.get("description")

        if not name:
            console.print(
                "[red]SKILL.md frontmatter must include a 'name' field.[/red]"
            )

View on GitHub (pinned to 754d7323be)

Solutions

1. Commit all changes, push, and pull: `git add -A && git commit -m '...' && git push && git pull --rebase`, then re-run `crewai skill publish`.
2. If git cleanliness is not required (e.g. local-only experiment), use `crewai skill publish --force`.

Example fix

# before
vim SKILL.md   # bump version
crewai skill publish   # Failed to publish skill. Local changes need to be resolved...

# after
git add SKILL.md && git commit -m "bump skill version" && git push
crewai skill publish

import subprocess

def repo_is_clean_and_synced() -> bool:
    def ok(*args):
        return subprocess.run(["git", *args], capture_output=True).returncode == 0
    return ok("diff", "--quiet") and ok("diff", "--cached", "--quiet") and ok("diff", "--quiet", "@{u}")

When it happens

Trigger: Running `crewai skill publish` with modified/untracked files, local commits not pushed, or remote commits not pulled. The exact condition is `repository is not None and not repository.is_synced()` inside the non-`--force` branch.

Common situations: Editing SKILL.md (e.g. bumping the version) and immediately publishing without committing; working on a branch never pushed; collaborating where a teammate pushed after your last pull.

Related errors

• Unable to validate git state: {exc} Fix the issue or pass --
• No SKILL.md found in current directory. Run this command fro
• Failed to parse SKILL.md frontmatter: {exc}
• SKILL.md frontmatter must include a 'name' field.
• SKILL.md frontmatter must include a 'version' field before p

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/e5f23ad124cd34cb. Report an issue: GitHub.