Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions docs/integrations/alquimia.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,10 @@ Skills are installed as `.alquimia/skills/speckit-<command>/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

Expand Down
4 changes: 4 additions & 0 deletions docs/integrations/claude.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@ Skills are installed as `.claude/skills/speckit-<command>/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
Expand Down
6 changes: 5 additions & 1 deletion docs/integrations/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
16 changes: 15 additions & 1 deletion src/specify_cli/agents.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)

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).

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(
Expand Down
267 changes: 267 additions & 0 deletions tests/specify_cli/test_agents.py
Original file line number Diff line number Diff line change
@@ -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 = "<target> [--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="<target>",
)

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: "<env> [--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"] == "<env> [--force]"
assert parsed["user-invocable"] is True
assert parsed["disable-model-invocation"] is False