From 92e209eb7d9e269037febc66c9487ff84ee58a39 Mon Sep 17 00:00:00 2001 From: adityajai119 Date: Mon, 16 Nov 2026 22:22:06 +0530 Subject: [PATCH 1/2] fix(agents): apply argument-hint and skill post-processing in render_skill_command Fixes #5448. CommandRegistrar.render_skill_command() writes SKILL.md files for native /SKILL.md integrations during extension installation and preset command alias registration, before _register_extension_skills() or _register_skills() can touch those targets. Look up the target integration, apply apply_argument_hint() prior to frontmatter serialization, and run post_process_skill_content() afterward so generated skills match the other SKILL.md generators. Assisted-by: OpenCode (model: Gemini 4 Carbon, autonomous) --- src/specify_cli/agents.py | 16 +- tests/specify_cli/test_agents.py | 267 +++++++++++++++++++++++++++++++ 2 files changed, 282 insertions(+), 1 deletion(-) create mode 100644 tests/specify_cli/test_agents.py diff --git a/src/specify_cli/agents.py b/src/specify_cli/agents.py index 8f3668812f..9e131249bc 100644 --- a/src/specify_cli/agents.py +++ b/src/specify_cli/agents.py @@ -440,7 +440,21 @@ def render_skill_command( f"{source_id}:{source_file}", author=author, ) - return self.render_frontmatter(skill_frontmatter) + "\n" + body + integration = None + try: + from specify_cli.integrations import get_integration + + integration = get_integration(agent_name) + except (ImportError, ValueError, KeyError): + pass + + self.apply_argument_hint(frontmatter, skill_frontmatter, integration) + skill_content = self.render_frontmatter(skill_frontmatter) + "\n" + body + if integration is not None and hasattr( + integration, "post_process_skill_content" + ): + skill_content = integration.post_process_skill_content(skill_content) + return skill_content @staticmethod def build_skill_frontmatter( diff --git a/tests/specify_cli/test_agents.py b/tests/specify_cli/test_agents.py new file mode 100644 index 0000000000..17b5a810f8 --- /dev/null +++ b/tests/specify_cli/test_agents.py @@ -0,0 +1,267 @@ +from __future__ import annotations + +from pathlib import Path + +import pytest +import yaml +from typer.testing import CliRunner + +from specify_cli import app + + +def _parse_skill_frontmatter(skill_file: Path) -> dict: + content = skill_file.read_text(encoding="utf-8") + assert content.startswith("---\n") + lines = content.splitlines(keepends=True) + end = next(i for i in range(1, len(lines)) if lines[i].rstrip("\r\n") == "---") + parsed = yaml.safe_load("".join(lines[1:end])) + assert isinstance(parsed, dict) + return parsed + + +def _write_hint_extension(ext_dir: Path, *, description: str, arg_hint: str) -> Path: + (ext_dir / "commands").mkdir(parents=True) + (ext_dir / "extension.yml").write_text( + yaml.safe_dump( + { + "schema_version": "1.0", + "extension": { + "id": "hint-ext", + "name": "Hint Extension", + "version": "1.0.0", + "description": "Extension with argument-hint", + "author": "ext-author", + "repository": "https://example.com", + "license": "MIT", + }, + "requires": {"speckit_version": ">=0.1.0"}, + "provides": { + "commands": [ + { + "name": "speckit.hint-ext.run", + "file": "commands/run.md", + "description": description, + "aliases": ["speckit.hint-ext.go"], + } + ] + }, + } + ), + encoding="utf-8", + ) + (ext_dir / "commands" / "run.md").write_text( + f'---\ndescription: "{description}"\nargument-hint: "{arg_hint}"\n---\n\nRun $ARGUMENTS\n', + encoding="utf-8", + ) + return ext_dir + + +def test_extension_add_preserves_argument_hint_and_skill_flags_for_claude( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + runner = CliRunner() + project = tmp_path / "proj" + init_res = runner.invoke( + app, + [ + "init", + str(project), + "--integration", + "claude", + "--ignore-agent-tools", + "--non-interactive", + ], + ) + assert init_res.exit_code == 0, init_res.output + + long_description = ( + "Build and maintain a lean static context folder so coding agents " + "load only relevant files and preserve token budget across runs" + ) + arg_hint = " [--dry-run] [--notes]" + ext_dir = _write_hint_extension( + tmp_path / "hint-ext", + description=long_description, + arg_hint=arg_hint, + ) + + monkeypatch.chdir(project) + add_res = runner.invoke(app, ["extension", "add", str(ext_dir), "--dev"]) + assert add_res.exit_code == 0, add_res.output + + for skill_name in ("speckit-hint-ext-run", "speckit-hint-ext-go"): + skill_file = project / ".claude" / "skills" / skill_name / "SKILL.md" + assert skill_file.is_file() + parsed = _parse_skill_frontmatter(skill_file) + assert parsed["name"] == skill_name + assert parsed["description"] == long_description + assert parsed["argument-hint"] == arg_hint + assert parsed["user-invocable"] is True + assert parsed["disable-model-invocation"] is False + + +def test_extension_add_gates_argument_hint_and_applies_agent_skill_flags( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + runner = CliRunner() + ext_dir = _write_hint_extension( + tmp_path / "hint-ext", + description="Run command", + arg_hint="", + ) + + codex_project = tmp_path / "codex-proj" + assert ( + runner.invoke( + app, + [ + "init", + str(codex_project), + "--integration", + "codex", + "--ignore-agent-tools", + "--non-interactive", + ], + ).exit_code + == 0 + ) + monkeypatch.chdir(codex_project) + assert ( + runner.invoke(app, ["extension", "add", str(ext_dir), "--dev"]).exit_code == 0 + ) + codex_fm = _parse_skill_frontmatter( + codex_project / ".agents" / "skills" / "speckit-hint-ext-run" / "SKILL.md" + ) + assert "argument-hint" not in codex_fm + assert "user-invocable" not in codex_fm + + droid_project = tmp_path / "droid-proj" + assert ( + runner.invoke( + app, + [ + "init", + str(droid_project), + "--integration", + "droid", + "--ignore-agent-tools", + "--non-interactive", + ], + ).exit_code + == 0 + ) + monkeypatch.chdir(droid_project) + assert ( + runner.invoke(app, ["extension", "add", str(ext_dir), "--dev"]).exit_code == 0 + ) + droid_fm = _parse_skill_frontmatter( + droid_project / ".factory" / "skills" / "speckit-hint-ext-run" / "SKILL.md" + ) + assert "argument-hint" not in droid_fm + assert droid_fm["user-invocable"] is True + assert droid_fm["disable-model-invocation"] is False + + +@pytest.mark.parametrize( + ("integration", "skills_rel", "expected_hook_example"), + [ + ("claude", ".claude/skills", "`/speckit-git-commit`"), + ("codex", ".agents/skills", "`$speckit-git-commit`"), + ], +) +def test_bundled_github_extension_skill_receives_hook_command_note( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + integration: str, + skills_rel: str, + expected_hook_example: str, +) -> None: + runner = CliRunner() + project = tmp_path / f"{integration}-proj" + init_res = runner.invoke( + app, + [ + "init", + str(project), + "--integration", + integration, + "--extension", + "github", + "--ignore-agent-tools", + "--non-interactive", + ], + ) + assert init_res.exit_code == 0, init_res.output + + skill_file = ( + project / skills_rel / "speckit-github-taskstoissues" / "SKILL.md" + ) + assert skill_file.is_file() + content = skill_file.read_text(encoding="utf-8") + assert expected_hook_example in content + + +def test_preset_command_alias_skill_preserves_argument_hint_and_flags( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + runner = CliRunner() + project = tmp_path / "proj" + init_res = runner.invoke( + app, + [ + "init", + str(project), + "--integration", + "claude", + "--ignore-agent-tools", + "--non-interactive", + ], + ) + assert init_res.exit_code == 0, init_res.output + + preset_dir = tmp_path / "deploy-preset" + (preset_dir / "commands").mkdir(parents=True) + (preset_dir / "preset.yml").write_text( + yaml.safe_dump( + { + "schema_version": "1.0", + "preset": { + "id": "deploy-preset", + "name": "Deploy Preset", + "version": "1.0.0", + "description": "Preset with aliased command", + "author": "preset-author", + "license": "MIT", + }, + "requires": {"speckit_version": ">=0.1.0"}, + "provides": { + "templates": [ + { + "type": "command", + "name": "speckit.custom.deploy", + "file": "commands/deploy.md", + "description": "Deploy command", + "aliases": ["speckit.custom.ship"], + } + ] + }, + } + ), + encoding="utf-8", + ) + (preset_dir / "commands" / "deploy.md").write_text( + '---\ndescription: "Deploy command"\nargument-hint: " [--force]"\n---\n\nDeploy $ARGUMENTS\n', + encoding="utf-8", + ) + + monkeypatch.chdir(project) + add_res = runner.invoke(app, ["preset", "add", "--dev", str(preset_dir)]) + assert add_res.exit_code == 0, add_res.output + + for skill_name in ("speckit-custom-deploy", "speckit-custom-ship"): + skill_file = project / ".claude" / "skills" / skill_name / "SKILL.md" + assert skill_file.is_file() + parsed = _parse_skill_frontmatter(skill_file) + assert parsed["argument-hint"] == " [--force]" + assert parsed["user-invocable"] is True + assert parsed["disable-model-invocation"] is False From 9c3e20ab8c3b8954b4b429dc3408ac9bbca13be4 Mon Sep 17 00:00:00 2001 From: adityajai119 Date: Tue, 17 Nov 2026 13:10:57 +0530 Subject: [PATCH 2/2] docs(integrations): document skill argument-hint retention and hook-command guidance Assisted-by: OpenCode (model: Gemini 4 Carbon, autonomous) --- docs/integrations/alquimia.md | 6 ++++-- docs/integrations/claude.md | 4 ++++ docs/integrations/cli.md | 6 +++++- 3 files changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/integrations/alquimia.md b/docs/integrations/alquimia.md index 184a360c12..038e3cc65d 100644 --- a/docs/integrations/alquimia.md +++ b/docs/integrations/alquimia.md @@ -23,8 +23,10 @@ Skills are installed as `.alquimia/skills/speckit-/SKILL.md`. Invoke them in the agent's chat, for example `/speckit-specify` or `/speckit-bug-assess` for the installed bug extension. -Generated skills are both user- and model-invocable; supported core skills also -receive inline argument hints. +Generated skills are both user- and model-invocable; supported core skills +receive inline `argument-hint` frontmatter, and extension commands and preset +command aliases retain any `argument-hint` declared in their source command +frontmatter. ## Workflow Dispatch diff --git a/docs/integrations/claude.md b/docs/integrations/claude.md index 3bb067f1fb..b4e8d60560 100644 --- a/docs/integrations/claude.md +++ b/docs/integrations/claude.md @@ -23,6 +23,10 @@ Skills are installed as `.claude/skills/speckit-/SKILL.md`. Invoke them in Claude's chat, for example `/speckit-specify` or `/speckit-bug-assess` for the installed bug extension. +Supported core skills receive inline `argument-hint` frontmatter, and extension +commands and preset command aliases retain any `argument-hint` declared in their +source command frontmatter. + ## User-Invocable-Only Skills By default every Spec Kit skill installed for Claude Code is model-invocable, so diff --git a/docs/integrations/cli.md b/docs/integrations/cli.md index b418d83251..db1cb9cfde 100644 --- a/docs/integrations/cli.md +++ b/docs/integrations/cli.md @@ -28,7 +28,11 @@ agent and its installed mode: | Codex, Command Code, ZCode skills | `$speckit-specify` | `$speckit-bug-assess` | | Kimi skills | `/skill:speckit-specify` | `/skill:speckit-bug-assess` | -Use the form exposed by your agent. See the +Use the form exposed by your agent. In skills-backed integrations, generated +core, extension, and preset skills include hook-command guidance translating +dotted hook command names (such as `speckit.git.commit`) into the active +integration's hyphenated skill invocation (such as `/speckit-git-commit` or +`$speckit-git-commit`). See the [GitHub Copilot guide](copilot.md) for its skills and commands layouts, or choose another agent from the [integration directory](index.md).