Skip to content

💫 Toolkit to help you get started with SDD or any other process!

fix(skills): preserve non-ASCII characters in skill frontmatter (#2917)

Seiya Kojima811a3aa447ed
diff --git a/src/specify_cli/_utils.py b/src/specify_cli/_utils.py
index 6daab0831..30c59f553 100644
--- a/src/specify_cli/_utils.py
+++ b/src/specify_cli/_utils.py
@@ -8,6 +8,7 @@ import shutil
import stat
import subprocess
import tempfile
+import yaml
from pathlib import Path
from typing import Any
from ._console import console
@@ -16,6 +17,16 @@ CLAUDE_LOCAL_PATH = Path.home() / ".claude" / "local" / "claude"
CLAUDE_NPM_LOCAL_PATH = Path.home() / ".claude" / "local" / "node_modules" / ".bin" / "claude"
+def dump_frontmatter(data: dict[str, Any]) -> str:
+ """Serialize skill/command frontmatter to a YAML string.
+
+ Centralizes the dump options used for SKILL.md frontmatter: ``allow_unicode``
+ preserves Unicode descriptions and ``sort_keys=False`` keeps key order, so no
+ call site can silently drop either.
+ """
+ return yaml.safe_dump(data, sort_keys=False, allow_unicode=True).strip()
+
+
def run_command(cmd: list[str], check_return: bool = True, capture: bool = False, shell: bool = False) -> str | None:
"""Run a shell command and optionally capture output."""
try:
diff --git a/src/specify_cli/extensions.py b/src/specify_cli/extensions.py
index fa287a934..29b49b8d2 100644
--- a/src/specify_cli/extensions.py
+++ b/src/specify_cli/extensions.py
@@ -28,6 +28,7 @@ from packaging.specifiers import InvalidSpecifier, SpecifierSet
from ._init_options import is_ai_skills_enabled
from ._invocation_style import is_slash_skills_agent
+from ._utils import dump_frontmatter
from .catalogs import CatalogEntry as BaseCatalogEntry
from .catalogs import CatalogStackBase
@@ -1073,7 +1074,7 @@ class ExtensionManager:
and hasattr(integration, "inject_argument_hint")
):
frontmatter_data["argument-hint"] = str(argument_hint)
- frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
+ frontmatter_text = dump_frontmatter(frontmatter_data)
# Derive a human-friendly title from the command name
short_name = cmd_name
diff --git a/src/specify_cli/integrations/claude/__init__.py b/src/specify_cli/integrations/claude/__init__.py
index 57ecb354a..6a7d483db 100644
--- a/src/specify_cli/integrations/claude/__init__.py
+++ b/src/specify_cli/integrations/claude/__init__.py
@@ -5,10 +5,9 @@ from __future__ import annotations
from pathlib import Path
from typing import Any
-import yaml
-
from ..base import SkillsIntegration
from ..manifest import IntegrationManifest
+from ..._utils import dump_frontmatter
# Mapping of command template stem → argument-hint text shown inline
# when a user invokes the slash command in Claude Code.
@@ -103,7 +102,7 @@ class ClaudeIntegration(SkillsIntegration):
skill_frontmatter = self._build_skill_fm(
skill_name, description, f"templates/commands/{template_name}.md"
)
- frontmatter_text = yaml.safe_dump(skill_frontmatter, sort_keys=False).strip()
+ frontmatter_text = dump_frontmatter(skill_frontmatter)
return f"---\n{frontmatter_text}\n---\n\n{body.strip()}\n"
def _build_skill_fm(self, name: str, description: str, source: str) -> dict:
diff --git a/src/specify_cli/presets/__init__.py b/src/specify_cli/presets/__init__.py
index 8058bc355..f8b9bac69 100644
--- a/src/specify_cli/presets/__init__.py
+++ b/src/specify_cli/presets/__init__.py
@@ -30,6 +30,7 @@ from packaging.specifiers import SpecifierSet, InvalidSpecifier
from ..extensions import REINSTALL_COMMAND, ExtensionRegistry, normalize_priority
from .._init_options import is_ai_skills_enabled
from ..integrations.base import IntegrationBase
+from .._utils import dump_frontmatter
def _substitute_core_template(
@@ -1068,7 +1069,7 @@ class PresetManager:
skill_name, desc,
f"override:{cmd_name}",
)
- fm_text = yaml.safe_dump(fm_data, sort_keys=False).strip()
+ fm_text = dump_frontmatter(fm_data)
skill_title = self._skill_title_from_command(cmd_name)
skill_content = (
f"---\n{fm_text}\n---\n\n"
@@ -1345,7 +1346,7 @@ class PresetManager:
enhanced_desc,
f"preset:{manifest.id}",
)
- frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
+ frontmatter_text = dump_frontmatter(frontmatter_data)
skill_content = (
f"---\n"
f"{frontmatter_text}\n"
@@ -1441,7 +1442,7 @@ class PresetManager:
enhanced_desc,
f"templates/commands/{short_name}.md",
)
- frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
+ frontmatter_text = dump_frontmatter(frontmatter_data)
skill_title = self._skill_title_from_command(short_name)
skill_content = (
f"---\n"
@@ -1478,7 +1479,7 @@ class PresetManager:
frontmatter.get("description", f"Extension command: {command_name}"),
extension_restore["source"],
)
- frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
+ frontmatter_text = dump_frontmatter(frontmatter_data)
skill_content = (
f"---\n"
f"{frontmatter_text}\n"
@@ -3276,7 +3277,7 @@ class PresetResolver:
if top_fm:
top_frontmatter_text = (
"---\n"
- + yaml.safe_dump(top_fm, sort_keys=False).strip()
+ + dump_frontmatter(top_fm)
+ "\n---"
)
else:
diff --git a/tests/integrations/test_integration_claude.py b/tests/integrations/test_integration_claude.py
index 0a5a2b18f..aafc7b11d 100644
--- a/tests/integrations/test_integration_claude.py
+++ b/tests/integrations/test_integration_claude.py
@@ -66,6 +66,16 @@ class TestClaudeIntegration:
assert parsed["disable-model-invocation"] is False
assert parsed["metadata"]["source"] == "templates/commands/plan.md"
+ def test_render_skill_unicode(self):
+ """Test rendering a skill preserves non-ASCII characters."""
+ integration = get_integration("claude")
+ rendered = integration._render_skill(
+ "constitution",
+ {"description": "Prüfe Konformität der Implementierung"},
+ "Body",
+ )
+ assert "Prüfe Konformität" in rendered
+
def test_setup_upserts_context_section(self, tmp_path):
integration = get_integration("claude")
manifest = IntegrationManifest("claude", tmp_path)
diff --git a/tests/test_extension_skills.py b/tests/test_extension_skills.py
index 67eda3b6c..bc9591715 100644
--- a/tests/test_extension_skills.py
+++ b/tests/test_extension_skills.py
@@ -90,7 +90,7 @@ def _create_extension_dir(temp_dir: Path, ext_id: str = "test-ext") -> Path:
}
with open(ext_dir / "extension.yml", "w") as f:
- yaml.dump(manifest_data, f)
+ yaml.safe_dump(manifest_data, f)
commands_dir = ext_dir / "commands"
commands_dir.mkdir()
@@ -119,6 +119,50 @@ def _create_extension_dir(temp_dir: Path, ext_id: str = "test-ext") -> Path:
return ext_dir
+def _create_unicode_extension_dir(temp_dir: Path, ext_id: str = "uni-ext") -> Path:
+ """Create an extension whose command description contains non-ASCII characters."""
+ ext_dir = temp_dir / ext_id
+ ext_dir.mkdir()
+ description = "Prüfe Konformität der Implementierung"
+
+ manifest_data = {
+ "schema_version": "1.0",
+ "extension": {
+ "id": ext_id,
+ "name": "Unicode Extension",
+ "version": "1.0.0",
+ "description": description,
+ },
+ "requires": {"speckit_version": ">=0.1.0"},
+ "provides": {
+ "commands": [
+ {
+ "name": f"speckit.{ext_id}.hello",
+ "file": "commands/hello.md",
+ "description": description,
+ },
+ ]
+ },
+ }
+
+ with open(ext_dir / "extension.yml", "w", encoding="utf-8") as f:
+ yaml.safe_dump(manifest_data, f, allow_unicode=True)
+
+ commands_dir = ext_dir / "commands"
+ commands_dir.mkdir()
+ (commands_dir / "hello.md").write_text(
+ "---\n"
+ f'description: "{description}"\n'
+ "---\n"
+ "\n"
+ "# Hello\n"
+ "\n"
+ "Body.\n",
+ encoding="utf-8",
+ )
+ return ext_dir
+
+
def _can_create_symlink(temp_dir: Path) -> bool:
"""Return True when the current platform/user can create file symlinks."""
target = temp_dir / "symlink-target.txt"
@@ -432,6 +476,18 @@ class TestExtensionSkillRegistration:
parsed = yaml.safe_load(skill_file.read_text(encoding="utf-8").split("---", 2)[1])
assert "argument-hint" not in parsed
+ def test_skill_md_unicode(self, skills_project, temp_dir):
+ """SKILL.md generation should preserve non-ASCII characters."""
+ project_dir, skills_dir = skills_project
+ ext_dir = _create_unicode_extension_dir(temp_dir)
+ manager = ExtensionManager(project_dir)
+ manager.install_from_directory(ext_dir, "0.1.0", register_commands=False)
+
+ skill_file = skills_dir / "speckit-uni-ext-hello" / "SKILL.md"
+ content = skill_file.read_text(encoding="utf-8")
+
+ assert "Prüfe Konformität" in content
+
def test_no_skills_when_ai_skills_disabled(self, no_skills_project, extension_dir):
"""No skills should be created when ai_skills is false."""
manager = ExtensionManager(no_skills_project)
@@ -692,7 +748,7 @@ class TestExtensionSkillRegistration:
},
}
with open(ext_dir / "extension.yml", "w") as f:
- yaml.dump(manifest_data, f)
+ yaml.safe_dump(manifest_data, f)
(ext_dir / "commands").mkdir()
(ext_dir / "commands" / "plan.md").write_text(
@@ -747,7 +803,7 @@ class TestExtensionSkillRegistration:
},
}
with open(ext_dir / "extension.yml", "w") as f:
- yaml.dump(manifest_data, f)
+ yaml.safe_dump(manifest_data, f)
(ext_dir / "commands").mkdir()
(ext_dir / "commands" / "exists.md").write_text(
@@ -1303,7 +1359,7 @@ class TestExtensionSkillEdgeCases:
},
}
with open(ext_dir / "extension.yml", "w") as f:
- yaml.dump(manifest_data, f)
+ yaml.safe_dump(manifest_data, f)
(ext_dir / "commands").mkdir()
(ext_dir / "commands" / "plain.md").write_text(
@@ -1390,7 +1446,7 @@ class TestExtensionSkillEdgeCases:
},
}
with open(ext_dir / "extension.yml", "w") as f:
- yaml.dump(manifest_data, f)
+ yaml.safe_dump(manifest_data, f)
(ext_dir / "commands").mkdir()
# Malformed YAML: invalid key-value syntax