π« Toolkit to help you get started with SDD or any other process!
fix(presets): preserve argument-hint in preset SKILL.md generation (#2978)
Ali jawwadf9c6cf83e566
diff --git a/src/specify_cli/agents.py b/src/specify_cli/agents.pyindex 3c0641801..be9859bd0 100644--- a/src/specify_cli/agents.py+++ b/src/specify_cli/agents.py@@ -356,6 +356,33 @@ class CommandRegistrar:}return skill_frontmatter+ @staticmethod+ def apply_argument_hint(+ source_frontmatter: Dict[str, Any],+ skill_frontmatter: Dict[str, Any],+ integration: Optional[object] = None,+ ) -> None:+ """Carry a command's ``argument-hint`` into its generated skill frontmatter.++ Copies ``argument-hint`` from the parsed source command frontmatter into+ *skill_frontmatter* (mutated in place) before serialization, so that a+ folded multi-line ``description`` cannot be split into invalid YAML. Only+ integrations that support the field β those exposing+ ``inject_argument_hint`` (currently Claude) β receive the key, leaving+ :meth:`build_skill_frontmatter`'s shared shape unchanged for every other+ agent. Built-in templates carry no ``argument-hint``, so this is a no-op+ for the core path.+ """+ if not isinstance(source_frontmatter, dict) or not isinstance(skill_frontmatter, dict):+ return+ argument_hint = source_frontmatter.get("argument-hint")+ if (+ argument_hint+ and integration is not None+ and hasattr(integration, "inject_argument_hint")+ ):+ skill_frontmatter["argument-hint"] = str(argument_hint)+@staticmethoddef resolve_skill_placeholders(agent_name: str, frontmatter: dict, body: str, project_root: Pathdiff --git a/src/specify_cli/extensions.py b/src/specify_cli/extensions.pyindex 42ba2fe88..7efd5b424 100644--- a/src/specify_cli/extensions.py+++ b/src/specify_cli/extensions.py@@ -1061,20 +1061,10 @@ class ExtensionManager:)# Preserve the command's argument-hint in the generated skill,# mirroring the core template path (ClaudeIntegration.setup injects- # it for built-in commands). The value is added to the frontmatter- # dict before serialization β rather than via the string-based- # inject_argument_hint helper β so that a folded multi-line- # description cannot be split by the inserted line. Gated on the- # integration exposing inject_argument_hint so only argument-hint- # aware agents receive the key, leaving build_skill_frontmatter's- # shared shape unchanged for every other agent.- argument_hint = frontmatter.get("argument-hint")- if (- argument_hint- and integration is not None- and hasattr(integration, "inject_argument_hint")- ):- frontmatter_data["argument-hint"] = str(argument_hint)+ # it for built-in commands). See CommandRegistrar.apply_argument_hint+ # for why the value is added to the dict before serialization rather+ # than via the string-based inject_argument_hint helper.+ registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)frontmatter_text = dump_frontmatter(frontmatter_data)# Derive a human-friendly title from the command namediff --git a/src/specify_cli/presets/__init__.py b/src/specify_cli/presets/__init__.pyindex f8b9bac69..b30c6f3c1 100644--- a/src/specify_cli/presets/__init__.py+++ b/src/specify_cli/presets/__init__.py@@ -1064,11 +1064,14 @@ class PresetManager:body = self._resolve_skill_command_refs(body, registrar, selected_ai)+ from ..integrations import get_integration+ integration = get_integration(selected_ai) if isinstance(selected_ai, str) else Nonefm_data = registrar.build_skill_frontmatter(selected_ai if isinstance(selected_ai, str) else "",skill_name, desc,f"override:{cmd_name}",)+ registrar.apply_argument_hint(fm, fm_data, integration)fm_text = dump_frontmatter(fm_data)skill_title = self._skill_title_from_command(cmd_name)skill_content = (@@ -1076,8 +1079,6 @@ class PresetManager:f"# Speckit {skill_title} Skill\n\n{body}\n")# Apply integration post-processing (e.g. Claude flags)- from ..integrations import get_integration- integration = get_integration(selected_ai) if isinstance(selected_ai, str) else Noneif integration is not None and hasattr(integration, "post_process_skill_content"):skill_content = integration.post_process_skill_content(skill_content)skill_file.write_text(skill_content, encoding="utf-8")@@ -1346,6 +1347,7 @@ class PresetManager:enhanced_desc,f"preset:{manifest.id}",)+ registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)frontmatter_text = dump_frontmatter(frontmatter_data)skill_content = (f"---\n"@@ -1442,6 +1444,7 @@ class PresetManager:enhanced_desc,f"templates/commands/{short_name}.md",)+ registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)frontmatter_text = dump_frontmatter(frontmatter_data)skill_title = self._skill_title_from_command(short_name)skill_content = (@@ -1479,6 +1482,7 @@ class PresetManager:frontmatter.get("description", f"Extension command: {command_name}"),extension_restore["source"],)+ registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)frontmatter_text = dump_frontmatter(frontmatter_data)skill_content = (f"---\n"diff --git a/tests/test_presets.py b/tests/test_presets.pyindex de6054d99..a64e28bb3 100644--- a/tests/test_presets.py+++ b/tests/test_presets.py@@ -2997,6 +2997,84 @@ class TestPresetSkills:metadata = manager.registry.get("self-test")assert "speckit-specify" in metadata.get("registered_skills", [])+ def _install_arg_hint_preset(self, project_dir, temp_dir, ai, skills_dir, description, arg_hint):+ """Install a preset whose command declares argument-hint; return the SKILL.md path."""+ self._write_init_options(project_dir, ai=ai)+ self._create_skill(skills_dir, "speckit-hinttest-cmd")+ (project_dir / ".specify" / "extensions" / "hinttest").mkdir(parents=True, exist_ok=True)++ preset_dir = temp_dir / f"hint-preset-{ai}"+ preset_dir.mkdir()+ (preset_dir / "commands").mkdir()+ (preset_dir / "commands" / "speckit.hinttest.cmd.md").write_text(+ "---\n"+ f'description: "{description}"\n'+ f'argument-hint: "{arg_hint}"\n'+ "---\n\n"+ "Preset command body.\n",+ encoding="utf-8",+ )+ manifest_data = {+ "schema_version": "1.0",+ "preset": {+ "id": f"hint-preset-{ai}",+ "name": "Hint Preset",+ "version": "1.0.0",+ "description": "Test",+ },+ "requires": {"speckit_version": ">=0.1.0"},+ "provides": {+ "templates": [+ {+ "type": "command",+ "name": "speckit.hinttest.cmd",+ "file": "commands/speckit.hinttest.cmd.md",+ }+ ]+ },+ }+ with open(preset_dir / "preset.yml", "w") as f:+ yaml.dump(manifest_data, f)++ manager = PresetManager(project_dir)+ manager.install_from_directory(preset_dir, "0.1.5")+ return skills_dir / "speckit-hinttest-cmd" / "SKILL.md"++ def test_argument_hint_preserved_for_preset_command(self, project_dir, temp_dir):+ """argument-hint from a preset command must survive into the SKILL.md.++ Follow-up to #2903/#2916 for the preset skill generator. The+ description is long enough to fold across lines when serialized,+ guarding against an in-place string injection that would split the+ folded scalar into invalid YAML.+ """+ long_description = (+ "Build and maintain a lean, static context/ knowledge folder so "+ "coding agents load only what is relevant and save tokens"+ )+ arg_hint = "<init | update | list | check> [area] [slug] [-- notes]"+ skills_dir = project_dir / ".claude" / "skills"++ skill_file = self._install_arg_hint_preset(+ project_dir, temp_dir, "claude", skills_dir, long_description, arg_hint+ )+ assert skill_file.exists()+ parsed = yaml.safe_load(skill_file.read_text(encoding="utf-8").split("---", 2)[1])+ assert parsed["argument-hint"] == arg_hint+ assert parsed["description"] == long_description++ def test_argument_hint_not_added_for_non_claude_preset_command(self, project_dir, temp_dir):+ """Non-Claude skills agents must not receive argument-hint in preset skills."""+ arg_hint = "<init | update | list | check> [area]"+ skills_dir = project_dir / ".agents" / "skills"++ skill_file = self._install_arg_hint_preset(+ project_dir, temp_dir, "codex", skills_dir, "Build context", arg_hint+ )+ assert skill_file.exists()+ parsed = yaml.safe_load(skill_file.read_text(encoding="utf-8").split("---", 2)[1])+ assert "argument-hint" not in parsed+def test_register_skills_resolves_command_refs(self, project_dir, temp_dir):"""Preset skill overrides must resolve __SPECKIT_COMMAND_*__ tokens (issue #2717).