fix(presets): preserve argument-hint in preset SKILL.md generation

[jawwad-ali]

Description

Follow-up to #2903 / #2916. That fix preserved argument-hint for extension commands when generating Claude SKILL.md; the same field is still dropped by the preset skill generators.

When a preset-provided command (or a preset override of an extension command) declares argument-hint: in its frontmatter, the generated .claude/skills/<name>/SKILL.md loses it, because the preset generators build the skill frontmatter via the shared CommandRegistrar.build_skill_frontmatter() (which only emits name / description / compatibility / metadata) and never forward argument-hint. It is also re-dropped on preset removal, when an overridden skill is restored from its source command — which silently undoes the #2916 extension fix in a real workflow (override an extension skill via a preset, then remove the preset).

Change

Rather than copy the #2916 inline block to each site, this factors the carry-over into one helper and reuses it:

• agents.py — new CommandRegistrar.apply_argument_hint(source_frontmatter, skill_frontmatter, integration). It copies argument-hint from the parsed source command frontmatter into the skill frontmatter dict, before yaml.safe_dump (so a folded multi-line description can't be split into invalid YAML — the failure mode fix(extensions): preserve argument-hint in extension Claude SKILL.md (#2903) #2916 documented), and only when the integration exposes inject_argument_hint.
• presets.py — applied at all four build_skill_frontmatter sites: _register_skills, the reconcile override-restore path, and the core/extension _unregister_skills restore paths.
• extensions.py — the fix(extensions): preserve argument-hint in extension Claude SKILL.md (#2903) #2916 inline block now calls the shared helper (no behavior change).

Why it's safe (no behavior change for non-Claude agents or the core path)

• inject_argument_hint is defined only on ClaudeIntegration (not inherited), so the hasattr gate adds the key for Claude only — build_skill_frontmatter's shared shape is byte-identical for every other agent (codex, kimi, …).
• Core command templates carry no argument-hint (0 of 9 templates/commands/*.md), so the core-template restore site is a deliberate no-op.
• The helper no-ops on a missing hint or a non-dict frontmatter.
• The one structural tweak — at the override-restore site, the existing get_integration(...) lookup is hoisted a few lines above build_skill_frontmatter so the hint can be applied pre-serialization — is a pure reorder: get_integration is a side-effect-free registry lookup, the same value still feeds post_process_skill_content, and there is no import cycle (it was already a method-local import).

Scope

Kept focused per CONTRIBUTING. The init-time agents.py::render_skill_command generator also omits argument-hint, but it takes an agent_name (no integration object) and so needs separate plumbing — deferred to a follow-up rather than widening this PR.

Heads-up on overlapping PRs

Open PRs #2917 ("preserve non-ASCII characters in skill frontmatter") and #2103 touch the same presets.py skill-generation lines. The concerns are orthogonal — apply_argument_hint mutates the frontmatter dict before whatever dump function runs, so it composes cleanly with #2917's dump_frontmatter() swap. Happy to rebase whichever lands first.

Testing

• Tested locally with uv run specify --help (exit 0)
• Ran existing tests with uv sync && uv run pytest
• Tested with a sample project (N/A — generation-only frontmatter change; covered by the unit tests below)

Details (Windows 11, Python 3.12.12):

• uvx ruff check src/ — All checks passed
• uv run pytest tests/test_presets.py tests/test_extension_skills.py tests/integrations/test_integration_claude.py -q — 397 passed, 2 skipped (the fix(extensions): preserve argument-hint in extension Claude SKILL.md (#2903) #2916 extension tests pass unchanged, confirming the refactor is behavior-preserving)
• Full suite uv run pytest — 3610 passed, 148 skipped, 14 failed; the 14 failures are pre-existing and environment-only (os.symlink → WinError 1314; creating symlinks needs elevation/Developer Mode on Windows), identical to clean main on this host and unrelated to this change.

New tests in tests/test_presets.py:

• test_argument_hint_preserved_for_preset_command — installs a preset command with argument-hint and a long, folding description; asserts the generated SKILL.md frontmatter parses and retains both argument-hint and the full description. (Fails on main with KeyError: 'argument-hint'.)
• test_argument_hint_not_added_for_non_claude_preset_command — same under a non-Claude skills agent (codex); asserts argument-hint is not present, proving the Claude-only gate.

Manual sanity: this changes only the emitted SKILL.md frontmatter — no slash command's behavior changes; generated files parse as valid YAML and surface the hint in Claude Code.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (describe below)

Developed with Claude Code (Claude Opus 4.8) under my direction — identifying the parallel preset drop sites, factoring the shared helper, writing the regression tests, and running the verification above. I personally confirmed the no-op behavior for non-Claude agents and the core path, verified the override-restore reorder is behavior-preserving, and reviewed the full diff before submitting. I'll disclose if any review responses are AI-assisted as well.

[Copilot]

Pull request overview

This PR ensures argument-hint declared in preset-provided (and preset-override/restore) command frontmatter is preserved in generated SKILL.md frontmatter for Claude, matching the earlier extension-path fix and preventing YAML breakage with folded descriptions.

Changes:

• Added CommandRegistrar.apply_argument_hint(...) to copy argument-hint into the skill frontmatter dict pre-serialization, gated on integrations that support it (Claude).
• Wired the helper into all preset skill generation/restore paths and refactored the extensions path to reuse the shared helper.
• Added preset-focused regression tests verifying (1) argument-hint is preserved for Claude and (2) not emitted for non-Claude skill agents.

Show a summary per file

File	Description
src/specify_cli/agents.py	Introduces the shared apply_argument_hint helper on CommandRegistrar.
src/specify_cli/presets.py	Applies the helper across preset skill generation and restore paths to preserve argument-hint.
src/specify_cli/extensions.py	Refactors the existing extension-path injection to call the shared helper.
tests/test_presets.py	Adds regression tests covering argument-hint preservation for preset-generated skills.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 4/4 changed files
• Comments generated: 1

[Copilot]

Copilot's findings

• Files reviewed: 4/4 changed files
• Comments generated: 1

[mnriem]

Please address Copilot feedback

[jawwad-ali]

Thanks for the review! Addressed in 5670d63:

• skill_frontmatter guard — apply_argument_hint() now early-returns on a non-dict skill_frontmatter too (symmetric with the source_frontmatter check), so it stays a safe no-op like the other frontmatter helpers in this module.
• Annotations — tightened to Dict[str, Any] for both frontmatter params and Optional[object] = None for integration, matching the real call sites (which can pass None).

I also rebased onto main to resolve the conflict with the now-merged #2917: apply_argument_hint() mutates the frontmatter dict before serialization, so it composes cleanly with the new dump_frontmatter() helper at every site. Local runs are green — tests/test_presets.py, tests/test_extension_skills.py, tests/integrations/test_integration_claude.py, tests/test_extensions.py → 692 passed, 3 skipped, including #2917's non-ASCII frontmatter tests.

Disclosure: this PR and this comment were prepared with Claude Code (Claude Opus 4.8) under my direction; I reviewed the diff and ran the tests before pushing.