Skip to content

Commit f9c6cf8

Browse files
jawwad-aliclaude
andauthored
fix(presets): preserve argument-hint in preset SKILL.md generation (#2978)
* fix(presets): preserve argument-hint in preset SKILL.md generation Preset-provided and extension-override commands that declare `argument-hint:` in their frontmatter had it dropped from the generated Claude SKILL.md, and it was re-dropped when a preset was removed and its overridden skill restored. This is the preset-side analog of the extension fix in #2903 / #2916. Factor the argument-hint carry-over into a shared CommandRegistrar.apply_argument_hint() helper and apply it at the four preset skill-generation sites (register, reconcile override-restore, and the core/extension unregister-restore paths). The extension path from The helper writes argument-hint into the frontmatter dict before serialization (so a folded multi-line description cannot be split into invalid YAML) and only for integrations that support it (those exposing inject_argument_hint -- currently Claude), leaving build_skill_frontmatter's shared shape unchanged for every other agent. Core templates carry no argument-hint, so the core-restore path is a no-op. No behavior change for non-Claude agents or the core path. Add regression tests covering a folding description (Claude) and the non-Claude gate (codex). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> * fix(presets): address review - guard skill_frontmatter type and tighten apply_argument_hint annotations Add a symmetric isinstance(skill_frontmatter, dict) guard so the helper stays a safe no-op if a caller passes a non-dict, and annotate the parameters as Dict[str, Any] with an optional integration to match real call-site usage. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
1 parent f5f7616 commit f9c6cf8

4 files changed

Lines changed: 115 additions & 16 deletions

File tree

‎src/specify_cli/agents.py‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -356,6 +356,33 @@ def build_skill_frontmatter(
356356
}
357357
return skill_frontmatter
358358

359+
@staticmethod
360+
def apply_argument_hint(
361+
source_frontmatter: Dict[str, Any],
362+
skill_frontmatter: Dict[str, Any],
363+
integration: Optional[object] = None,
364+
) -> None:
365+
"""Carry a command's ``argument-hint`` into its generated skill frontmatter.
366+
367+
Copies ``argument-hint`` from the parsed source command frontmatter into
368+
*skill_frontmatter* (mutated in place) before serialization, so that a
369+
folded multi-line ``description`` cannot be split into invalid YAML. Only
370+
integrations that support the field — those exposing
371+
``inject_argument_hint`` (currently Claude) — receive the key, leaving
372+
:meth:`build_skill_frontmatter`'s shared shape unchanged for every other
373+
agent. Built-in templates carry no ``argument-hint``, so this is a no-op
374+
for the core path.
375+
"""
376+
if not isinstance(source_frontmatter, dict) or not isinstance(skill_frontmatter, dict):
377+
return
378+
argument_hint = source_frontmatter.get("argument-hint")
379+
if (
380+
argument_hint
381+
and integration is not None
382+
and hasattr(integration, "inject_argument_hint")
383+
):
384+
skill_frontmatter["argument-hint"] = str(argument_hint)
385+
359386
@staticmethod
360387
def resolve_skill_placeholders(
361388
agent_name: str, frontmatter: dict, body: str, project_root: Path

‎src/specify_cli/extensions.py‎

Lines changed: 4 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1061,20 +1061,10 @@ def _register_extension_skills(
10611061
)
10621062
# Preserve the command's argument-hint in the generated skill,
10631063
# mirroring the core template path (ClaudeIntegration.setup injects
1064-
# it for built-in commands). The value is added to the frontmatter
1065-
# dict before serialization — rather than via the string-based
1066-
# inject_argument_hint helper — so that a folded multi-line
1067-
# description cannot be split by the inserted line. Gated on the
1068-
# integration exposing inject_argument_hint so only argument-hint
1069-
# aware agents receive the key, leaving build_skill_frontmatter's
1070-
# shared shape unchanged for every other agent.
1071-
argument_hint = frontmatter.get("argument-hint")
1072-
if (
1073-
argument_hint
1074-
and integration is not None
1075-
and hasattr(integration, "inject_argument_hint")
1076-
):
1077-
frontmatter_data["argument-hint"] = str(argument_hint)
1064+
# it for built-in commands). See CommandRegistrar.apply_argument_hint
1065+
# for why the value is added to the dict before serialization rather
1066+
# than via the string-based inject_argument_hint helper.
1067+
registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)
10781068
frontmatter_text = dump_frontmatter(frontmatter_data)
10791069

10801070
# Derive a human-friendly title from the command name

‎src/specify_cli/presets/__init__.py‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1064,20 +1064,21 @@ def _reconcile_skills(self, command_names: List[str]) -> None:
10641064
body = self._resolve_skill_command_refs(
10651065
body, registrar, selected_ai
10661066
)
1067+
from ..integrations import get_integration
1068+
integration = get_integration(selected_ai) if isinstance(selected_ai, str) else None
10671069
fm_data = registrar.build_skill_frontmatter(
10681070
selected_ai if isinstance(selected_ai, str) else "",
10691071
skill_name, desc,
10701072
f"override:{cmd_name}",
10711073
)
1074+
registrar.apply_argument_hint(fm, fm_data, integration)
10721075
fm_text = dump_frontmatter(fm_data)
10731076
skill_title = self._skill_title_from_command(cmd_name)
10741077
skill_content = (
10751078
f"---\n{fm_text}\n---\n\n"
10761079
f"# Speckit {skill_title} Skill\n\n{body}\n"
10771080
)
10781081
# Apply integration post-processing (e.g. Claude flags)
1079-
from ..integrations import get_integration
1080-
integration = get_integration(selected_ai) if isinstance(selected_ai, str) else None
10811082
if integration is not None and hasattr(integration, "post_process_skill_content"):
10821083
skill_content = integration.post_process_skill_content(skill_content)
10831084
skill_file.write_text(skill_content, encoding="utf-8")
@@ -1346,6 +1347,7 @@ def _register_skills(
13461347
enhanced_desc,
13471348
f"preset:{manifest.id}",
13481349
)
1350+
registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)
13491351
frontmatter_text = dump_frontmatter(frontmatter_data)
13501352
skill_content = (
13511353
f"---\n"
@@ -1442,6 +1444,7 @@ def _unregister_skills(self, skill_names: List[str], preset_dir: Path) -> None:
14421444
enhanced_desc,
14431445
f"templates/commands/{short_name}.md",
14441446
)
1447+
registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)
14451448
frontmatter_text = dump_frontmatter(frontmatter_data)
14461449
skill_title = self._skill_title_from_command(short_name)
14471450
skill_content = (
@@ -1479,6 +1482,7 @@ def _unregister_skills(self, skill_names: List[str], preset_dir: Path) -> None:
14791482
frontmatter.get("description", f"Extension command: {command_name}"),
14801483
extension_restore["source"],
14811484
)
1485+
registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)
14821486
frontmatter_text = dump_frontmatter(frontmatter_data)
14831487
skill_content = (
14841488
f"---\n"

‎tests/test_presets.py‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2997,6 +2997,84 @@ def test_skill_overridden_on_preset_install(self, project_dir, temp_dir):
29972997
metadata = manager.registry.get("self-test")
29982998
assert "speckit-specify" in metadata.get("registered_skills", [])
29992999

3000+
def _install_arg_hint_preset(self, project_dir, temp_dir, ai, skills_dir, description, arg_hint):
3001+
"""Install a preset whose command declares argument-hint; return the SKILL.md path."""
3002+
self._write_init_options(project_dir, ai=ai)
3003+
self._create_skill(skills_dir, "speckit-hinttest-cmd")
3004+
(project_dir / ".specify" / "extensions" / "hinttest").mkdir(parents=True, exist_ok=True)
3005+
3006+
preset_dir = temp_dir / f"hint-preset-{ai}"
3007+
preset_dir.mkdir()
3008+
(preset_dir / "commands").mkdir()
3009+
(preset_dir / "commands" / "speckit.hinttest.cmd.md").write_text(
3010+
"---\n"
3011+
f'description: "{description}"\n'
3012+
f'argument-hint: "{arg_hint}"\n'
3013+
"---\n\n"
3014+
"Preset command body.\n",
3015+
encoding="utf-8",
3016+
)
3017+
manifest_data = {
3018+
"schema_version": "1.0",
3019+
"preset": {
3020+
"id": f"hint-preset-{ai}",
3021+
"name": "Hint Preset",
3022+
"version": "1.0.0",
3023+
"description": "Test",
3024+
},
3025+
"requires": {"speckit_version": ">=0.1.0"},
3026+
"provides": {
3027+
"templates": [
3028+
{
3029+
"type": "command",
3030+
"name": "speckit.hinttest.cmd",
3031+
"file": "commands/speckit.hinttest.cmd.md",
3032+
}
3033+
]
3034+
},
3035+
}
3036+
with open(preset_dir / "preset.yml", "w") as f:
3037+
yaml.dump(manifest_data, f)
3038+
3039+
manager = PresetManager(project_dir)
3040+
manager.install_from_directory(preset_dir, "0.1.5")
3041+
return skills_dir / "speckit-hinttest-cmd" / "SKILL.md"
3042+
3043+
def test_argument_hint_preserved_for_preset_command(self, project_dir, temp_dir):
3044+
"""argument-hint from a preset command must survive into the SKILL.md.
3045+
3046+
Follow-up to #2903/#2916 for the preset skill generator. The
3047+
description is long enough to fold across lines when serialized,
3048+
guarding against an in-place string injection that would split the
3049+
folded scalar into invalid YAML.
3050+
"""
3051+
long_description = (
3052+
"Build and maintain a lean, static context/ knowledge folder so "
3053+
"coding agents load only what is relevant and save tokens"
3054+
)
3055+
arg_hint = "<init | update | list | check> [area] [slug] [-- notes]"
3056+
skills_dir = project_dir / ".claude" / "skills"
3057+
3058+
skill_file = self._install_arg_hint_preset(
3059+
project_dir, temp_dir, "claude", skills_dir, long_description, arg_hint
3060+
)
3061+
assert skill_file.exists()
3062+
parsed = yaml.safe_load(skill_file.read_text(encoding="utf-8").split("---", 2)[1])
3063+
assert parsed["argument-hint"] == arg_hint
3064+
assert parsed["description"] == long_description
3065+
3066+
def test_argument_hint_not_added_for_non_claude_preset_command(self, project_dir, temp_dir):
3067+
"""Non-Claude skills agents must not receive argument-hint in preset skills."""
3068+
arg_hint = "<init | update | list | check> [area]"
3069+
skills_dir = project_dir / ".agents" / "skills"
3070+
3071+
skill_file = self._install_arg_hint_preset(
3072+
project_dir, temp_dir, "codex", skills_dir, "Build context", arg_hint
3073+
)
3074+
assert skill_file.exists()
3075+
parsed = yaml.safe_load(skill_file.read_text(encoding="utf-8").split("---", 2)[1])
3076+
assert "argument-hint" not in parsed
3077+
30003078
def test_register_skills_resolves_command_refs(self, project_dir, temp_dir):
30013079
"""Preset skill overrides must resolve __SPECKIT_COMMAND_*__ tokens (issue #2717).
30023080

0 commit comments

Comments
 (0)