fix(skills): address review comments on the promotion PR

- Back-compat shim now aliases the old submodules in sys.modules so
  `crewai.experimental.skills.registry/cache/events` imports (and patch
  targets) resolve to the real crewai.skills modules, not just the
  package-root re-exports.
- `crewai skill publish` actually enforces the git-state check that
  --force claims to skip: unsynced repos block publishing (mirroring
  tool publish); standalone skill dirs outside any git repo publish
  without a check.
- Explicit UTF-8 encoding on SKILL.md and cache-metadata reads/writes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: joaomdmoura

lib/cli/src/crewai_cli/skills/main.py

@@ -13,6 +13,7 @@
 from rich.console import Console
 from rich.table import Table
 
+from crewai_cli import git
 from crewai_cli.command import BaseCommand, PlusAPIMixin
 from crewai_cli.config import Settings
 from crewai_cli.constants import DEFAULT_CREWAI_ENTERPRISE_URL
@@ -63,7 +64,7 @@ def create(self, name: str, in_project: bool = True) -> None:
         (skill_dir / "assets").mkdir()
 
         skill_md = skill_dir / "SKILL.md"
-        skill_md.write_text(_SKILL_MD_TEMPLATE.format(name=name))
+        skill_md.write_text(_SKILL_MD_TEMPLATE.format(name=name), encoding="utf-8")
 
         console.print(
             f"[green]Created skill [bold]{name}[/bold] at [bold]{skill_dir}[/bold].[/green]"
@@ -170,7 +171,9 @@ def install(self, ref: str) -> None:
                     "version": version,
                     "installed_at": datetime.now(tz=timezone.utc).isoformat(),
                 }
-                (cache_dir / ".crewai_meta.json").write_text(json.dumps(meta, indent=2))
+                (cache_dir / ".crewai_meta.json").write_text(
+                    json.dumps(meta, indent=2), encoding="utf-8"
+                )
             console.print(
                 f"[green]Installed [bold]{ref}[/bold]{' (' + version + ')' if version else ''} to global cache.[/green]"
             )
@@ -189,8 +192,27 @@ def publish(self, org: str | None = None, force: bool = False) -> None:
             )
             raise SystemExit(1)
 
+        if not force:
+            try:
+                repository = git.Repository()
+            except ValueError:
+                # Standalone skill directories may live outside any git repo;
+                # there is no git state to validate in that case.
+                repository = None
+            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())
+            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
@@ -281,7 +303,7 @@ def list_cached(self) -> None:
                     meta_file = skill_dir / ".crewai_meta.json"
                     if meta_file.exists():
                         try:
-                            meta = json.loads(meta_file.read_text())
+                            meta = json.loads(meta_file.read_text(encoding="utf-8"))
                             table.add_row(
                                 "cache",
                                 f"@{meta['org']}/{meta['name']}",
@@ -372,7 +394,7 @@ def _parse_frontmatter(self, content: str) -> dict[str, str]:
     def _read_version(self, skill_md: Path) -> str | None:
         """Read the version from a SKILL.md file's metadata, or None."""
         try:
-            fm = self._parse_frontmatter(skill_md.read_text())
+            fm = self._parse_frontmatter(skill_md.read_text(encoding="utf-8"))
             raw_metadata = fm.get("metadata")
             if isinstance(raw_metadata, dict):
                 return raw_metadata.get("version")

lib/cli/tests/skills/test_main.py

@@ -171,6 +171,60 @@ def test_publish_calls_api(self, skill_command):
             # Skills are always org-scoped; there is no public visibility.
             assert call_kwargs.kwargs["is_public"] is False
 
+    def test_publish_blocked_when_git_not_synced(self, skill_command):
+        with in_temp_dir():
+            Path("SKILL.md").write_text(
+                "---\nname: my-skill\ndescription: A test skill.\nmetadata:\n  version: 1.0.0\n---\nInstructions."
+            )
+            skill_command.plus_api_client.publish_skill = MagicMock()
+            with patch("crewai_cli.skills.main.git.Repository") as mock_repo_cls:
+                mock_repo_cls.return_value.is_synced.return_value = False
+                with pytest.raises(SystemExit):
+                    skill_command.publish(org="acme")
+            skill_command.plus_api_client.publish_skill.assert_not_called()
+
+    def test_publish_force_skips_git_check(self, skill_command):
+        with in_temp_dir():
+            Path("SKILL.md").write_text(
+                "---\nname: my-skill\ndescription: A test skill.\nmetadata:\n  version: 1.0.0\n---\nInstructions."
+            )
+            mock_resp = MagicMock()
+            mock_resp.is_success = True
+            mock_resp.status_code = 200
+            mock_resp.json.return_value = {}
+            skill_command.plus_api_client.publish_skill = MagicMock(return_value=mock_resp)
+            with (
+                patch("crewai_cli.skills.main.git.Repository") as mock_repo_cls,
+                patch("crewai_cli.skills.main.Settings") as mock_settings_cls,
+            ):
+                mock_settings_cls.return_value.org_name = "acme"
+                mock_settings_cls.return_value.enterprise_base_url = None
+                skill_command.publish(org="acme", force=True)
+            mock_repo_cls.assert_not_called()
+            skill_command.plus_api_client.publish_skill.assert_called_once()
+
+    def test_publish_proceeds_outside_git_repo(self, skill_command):
+        with in_temp_dir():
+            Path("SKILL.md").write_text(
+                "---\nname: my-skill\ndescription: A test skill.\nmetadata:\n  version: 1.0.0\n---\nInstructions."
+            )
+            mock_resp = MagicMock()
+            mock_resp.is_success = True
+            mock_resp.status_code = 200
+            mock_resp.json.return_value = {}
+            skill_command.plus_api_client.publish_skill = MagicMock(return_value=mock_resp)
+            with (
+                patch(
+                    "crewai_cli.skills.main.git.Repository",
+                    side_effect=ValueError("not a Git repository"),
+                ),
+                patch("crewai_cli.skills.main.Settings") as mock_settings_cls,
+            ):
+                mock_settings_cls.return_value.org_name = "acme"
+                mock_settings_cls.return_value.enterprise_base_url = None
+                skill_command.publish(org="acme")
+            skill_command.plus_api_client.publish_skill.assert_called_once()
+
 
 class TestSkillListCached:
     def test_list_cached_empty(self, skill_command, capsys):

lib/crewai/src/crewai/experimental/skills/__init__.py

@@ -2,10 +2,14 @@
 
 The registry-backed skills feature graduated out of experimental; it now
 lives in `crewai.skills` alongside the filesystem-based loader. This module
-re-exports the public names so imports written against the experimental
-namespace keep working, and will be removed in a future release.
+re-exports the public names and aliases the old submodules so imports
+written against the experimental namespace keep working, and will be
+removed in a future release.
 """
 
+import sys
+
+from crewai.skills import cache, events, registry
 from crewai.skills.cache import SkillCacheManager
 from crewai.skills.registry import (
     SkillNotCachedError,
@@ -15,10 +19,19 @@
 )
 
 
+# Keep `crewai.experimental.skills.<module>` imports (and patch targets)
+# resolving to the real modules in crewai.skills.
+sys.modules[__name__ + ".cache"] = cache
+sys.modules[__name__ + ".events"] = events
+sys.modules[__name__ + ".registry"] = registry
+
 __all__ = [
     "SkillCacheManager",
     "SkillNotCachedError",
+    "cache",
+    "events",
     "is_registry_ref",
     "parse_registry_ref",
+    "registry",
     "resolve_registry_ref",
 ]

lib/crewai/src/crewai/skills/cache.py

@@ -88,7 +88,9 @@ def store(
             "version": version,
             "installed_at": datetime.now(tz=timezone.utc).isoformat(),
         }
-        (skill_dir / _META_FILENAME).write_text(json.dumps(meta, indent=2))
+        (skill_dir / _META_FILENAME).write_text(
+            json.dumps(meta, indent=2), encoding="utf-8"
+        )
         return skill_dir
 
     def list_cached(self) -> list[SkillMetadata]:
@@ -103,7 +105,9 @@ def list_cached(self) -> list[SkillMetadata]:
                 meta_file = skill_dir / _META_FILENAME
                 if meta_file.exists():
                     try:
-                        results.append(json.loads(meta_file.read_text()))
+                        results.append(
+                            json.loads(meta_file.read_text(encoding="utf-8"))
+                        )
                     except (json.JSONDecodeError, KeyError):
                         _logger.debug(
                             "Skipping malformed cache entry: %s",

lib/crewai/tests/skills/test_experimental_shim.py

@@ -16,3 +16,23 @@ def test_experimental_namespace_reexports_public_names():
     assert experimental_skills.is_registry_ref is is_registry_ref
     assert experimental_skills.parse_registry_ref is parse_registry_ref
     assert experimental_skills.resolve_registry_ref is resolve_registry_ref
+
+
+def test_experimental_submodule_imports_alias_real_modules():
+    """Old submodule import style must resolve to the crewai.skills modules."""
+    from crewai.experimental.skills import cache as shim_cache
+    from crewai.experimental.skills import events as shim_events
+    from crewai.experimental.skills import registry as shim_registry
+    import crewai.experimental.skills.registry as shim_registry_direct
+    from crewai.experimental.skills.cache import SkillCacheManager
+    from crewai.experimental.skills.registry import resolve_registry_ref
+    import crewai.skills.cache
+    import crewai.skills.events
+    import crewai.skills.registry
+
+    assert shim_cache is crewai.skills.cache
+    assert shim_events is crewai.skills.events
+    assert shim_registry is crewai.skills.registry
+    assert shim_registry_direct is crewai.skills.registry
+    assert SkillCacheManager is crewai.skills.cache.SkillCacheManager
+    assert resolve_registry_ref is crewai.skills.registry.resolve_registry_ref