Skip to content

fix(agents): apply argument-hint and skill post-processing in render_skill_command - #5449

Open
adityajai119 wants to merge 2 commits into
github:mainfrom
adityajai119:fix/5448-render-skill-command-postprocess
Open

adityajai119 wants to merge 2 commits into
github:mainfrom
adityajai119:fix/5448-render-skill-command-postprocess

Conversation

@adityajai119

Copy link
Copy Markdown
Contributor

Description

Fixes #5448.

For native /SKILL.md integrations (claude, alquimia, droid, vibe, codex, kimi, agy, hermes), specify extension add, specify init --extension, and preset command alias registration render SKILL.md files via CommandRegistrar.register_commands() -> CommandRegistrar.render_skill_command().

Because _register_commands_for_active_agent() runs before _register_extension_skills() during ExtensionManager.install_from_directory(..., register_commands=True), _register_extension_skills() sees the file already on disk and skips it, and _PresetSkillMethods._register_skills() only re-renders primary command names (leaving aliases as rendered by render_skill_command()). Unlike the other SKILL.md generators, render_skill_command() neither applied apply_argument_hint() (left as a follow-up in #2978) nor called integration.post_process_skill_content(). As a result:

  • Extension commands and preset command aliases carrying argument-hint: lost argument-hint on Claude Code and Alquimia when installed through the CLI.
  • Extension skills on Claude Code, Factory Droid, Mistral Vibe, and Alquimia omitted user-invocable: true and disable-model-invocation: false.
  • Bundled and custom extension skills with hook blocks (such as speckit-github-taskstoissues from the github extension) omitted the skills-mode hook-command invocation note from SkillsIntegration.post_process_skill_content().

CommandRegistrar.render_skill_command() now resolves the target integration via get_integration(agent_name), calls self.apply_argument_hint(frontmatter, skill_frontmatter, integration) before YAML serialization so folded descriptions remain valid YAML, and runs integration.post_process_skill_content() when available.

Testing

Set up this checkout's .venv and editable install using the local development guide. Run commands from the checkout root.

  • Tested locally with .venv/bin/specify --help (Windows PowerShell: .\.venv\Scripts\specify.exe --help)
  • Ran relevant existing tests with .venv/bin/python -m pytest tests -q (Windows PowerShell: .\.venv\Scripts\python.exe -m pytest tests -q); use affected test paths for focused checks and LC_ALL=en_US.UTF-8 on macOS
  • Tested with a sample project (if applicable)

Verification details (Windows 11, Python 3.14.7):

  • Added tests/specify_cli/test_agents.py covering positive and negative cases through the CLI (claude extension command and alias with a folding description and argument-hint, codex and droid gating of argument-hint vs user-invocable/disable-model-invocation, bundled github extension hook-command note for claude and codex, and claude preset command alias preservation). Confirmed all 5 test cases fail on main (3050be0) and pass with the fix.
  • .\.venv\Scripts\python.exe -m pytest -n 2 tests/specify_cli/test_agents.py tests/test_extension_skills.py tests/test_extensions.py tests/test_presets.py tests/test_agent_config_consistency.py tests/specify_cli/extensions tests/extensions/github tests/integrations/test_integration_claude.py tests/integrations/test_integration_alquimia.py tests/integrations/test_integration_droid.py tests/integrations/test_integration_vibe.py -q: 1419 passed, 64 skipped.
  • .\.venv\Scripts\python.exe -m pytest -n 2 tests/specify_cli/presets tests/specify_cli/artifacts -q: 1149 passed, 1 skipped.
  • uvx ruff@0.15.0 check src tests and git diff --check: clean.
  • Sample project: ran .\.venv\Scripts\specify.exe init <temp>/speckit-sample-verify --integration claude --extension github --ignore-agent-tools --non-interactive and verified .claude/skills/speckit-github-taskstoissues/SKILL.md carries user-invocable: true, disable-model-invocation: false, and the skills-mode hook-command note.

AI Disclosure

  • I did not use AI assistance for this contribution
  • I did use AI assistance (fill in the disclosure below)

AI disclosure: Prepared on behalf of @adityajai119 by OpenCode using Gemini 4 Carbon (high reasoning effort, autonomous agent mode); bug discovery, root-cause diagnosis, code and regression test generation, local test and CLI verification, and PR drafting. No personal human line-by-line review is claimed.

…skill_command

Fixes github#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)
@adityajai119
adityajai119 requested a review from mnriem as a code owner November 16, 2026 16:52
Copilot AI adaptive review requested due to automatic review settings November 16, 2026 16:52

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified in the update aligning native skill rendering with other generators.

No open issues 🎉

What changed in this PR

Fixes #5448 by bringing native SKILL.md command rendering in line with other skill generators, preserving supported argument hints and applying integration-specific post-processing.

Changes:

  • Applies argument hints before YAML serialization and post-processes rendered skills to add invocation flags and hook-command guidance.
  • Adds CLI regression coverage for extension commands, aliases, agent-specific behavior, bundled GitHub hooks, and preset aliases.

The PR reports that all five regression cases fail before the fix and pass afterward; tests were not rerun during this review.

File Description
tests/​specify_cli/​test_agents.py Adds CLI regression tests for skill metadata and hook guidance.
src/​specify_cli/​agents.py Applies argument hints and integration post-processing in render_skill_command().

Review effort: Balanced (dynamic)

@mnriem mnriem added the triage-must-have Verdict: high-value, important work for Spec Kit — do first label Nov 16, 2026
@mnriem
mnriem requested an adaptive review from Copilot November 16, 2026 22:43

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The user-visible argument-hint and skill-generation changes lack required documentation updates in the Claude/Alquimia integration guides and shared CLI reference.

1 open issue

Review effort: Balanced (adaptive)

Comment thread src/specify_cli/agents.py
except (ImportError, ValueError, KeyError):
pass

self.apply_argument_hint(frontmatter, skill_frontmatter, integration)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated docs/integrations/claude.md, docs/integrations/alquimia.md, and docs/integrations/cli.md in 9c3e20a to document extension and preset alias argument-hint retention and the shared skills-mode hook-command guidance.

AI disclosure: drafted and verified autonomously by OpenCode (model: Gemini 4 Carbon).

…ommand guidance

Assisted-by: OpenCode (model: Gemini 4 Carbon, autonomous)
Copilot AI adaptive review requested due to automatic review settings November 17, 2026 07:41

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified in the changes aligning skill-command rendering with the other generators.

1 open issue

Review effort: Balanced (adaptive)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

triage-must-have Verdict: high-value, important work for Spec Kit — do first

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: CommandRegistrar.render_skill_command drops argument-hint and post_process_skill_content on native skills agents

3 participants