π« Toolkit to help you get started with SDD or any other process!
"""Agent skill registration and safe reconciliation for installed presets."""
import copy
import os
import shutil
from pathlib import Path
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Set, Union
if TYPE_CHECKING:
from ..agents import CommandRegistrar
from .._init_options import is_ai_skills_enabled
from .._invocation_style import get_invocation_prefix
from .._utils import dump_frontmatter
from ..integrations.base import IntegrationBase
from ..integrations._registration import project_registration
from ._manager_commands import _substitute_core_template
from ._manifest import PresetManifest, PresetValidationError
from ._resolver import PresetResolver
class _PresetSkillMethods:
"""Skill artifact methods shared through PresetManager's lifecycle state."""
class _FilteredManifest:
"""Wrapper that exposes only selected command templates from a manifest.
Used by _reconcile_skills to avoid overwriting skills for commands
that aren't being reconciled.
"""
def __init__(self, manifest: "PresetManifest", cmd_names: set):
self._manifest = manifest
self._cmd_names = cmd_names
def __getattr__(self, name: str):
return getattr(self._manifest, name)
@property
def templates(self) -> List[Dict[str, Any]]:
return [
t for t in self._manifest.templates
if t.get("name") in self._cmd_names
]
def _merge_pack_registered_skills(
self, pack_id: str, written: Optional[Dict[str, List[str]]]
) -> None:
"""Merge actually-written agent skill registrations into a preset's metadata.
Mirrors :meth:`_merge_pack_registered_commands` for the skills
side: ``_reconcile_skills`` can render a preset's SKILL.md content
into an agent directory the preset never wrote to before β most
notably a historical (currently inactive) agent restored via
``extra_skills_dirs`` when a higher-priority preset is removed. If
that write isn't reflected back into the winning preset's own
``registered_skills``, a later removal of this same preset only
cleans up the agents it already knew about, orphaning the skill
directory reconciliation just wrote to on its behalf (#2948).
Args:
pack_id: The preset whose metadata should be updated.
written: ``{agent_name: [skill_name, ...]}`` actually written
by the ``_register_skills`` call just made. A falsy value
is a no-op.
"""
if not written:
return
metadata = self.registry.get(pack_id)
if metadata is None:
return # pack_id no longer installed (e.g. removed mid-loop)
raw_existing_skills = metadata.get("registered_skills")
if isinstance(raw_existing_skills, list) and raw_existing_skills:
# Legacy flat-list value: infer real per-agent ownership from
# on-disk provenance rather than guessing (#2948).
fallback_agent = next(iter(written)) if written else None
existing_skills = self._infer_legacy_skill_provenance(
[n for n in raw_existing_skills if isinstance(n, str)],
pack_id,
fallback_agent=fallback_agent,
)
else:
existing_skills = self._normalize_registered_skills(raw_existing_skills)
merged_skills = copy.deepcopy(existing_skills)
changed = (
isinstance(raw_existing_skills, list) and bool(raw_existing_skills)
)
for agent_name, skill_names in written.items():
if not skill_names:
continue
existing_names = merged_skills.get(agent_name, [])
new_names = [n for n in skill_names if n not in existing_names]
if new_names:
merged_skills[agent_name] = existing_names + new_names
changed = True
if changed:
self.registry.update(pack_id, {"registered_skills": merged_skills})
@project_registration
def _reconcile_skills(
self,
command_names: List[str],
extra_skills_dirs: Optional[
Dict[Path, tuple[Optional[str], List[str]]]
] = None,
target_agent: Optional[str] = None,
) -> Set[str]:
"""Re-register skills for commands whose winning layer changed.
After a preset is removed, finds the next preset in the priority
stack that provides each command and re-runs skill registration
for that preset so SKILL.md files reflect the current winner.
Args:
command_names: List of command names to reconcile skills for
extra_skills_dirs: Additional
``{skills_dir: (renderer_agent, managed_skill_names)}``
entries restored by ``_unregister_skills``. Reconciliation
is limited to the names actually managed in each directory.
target_agent: If set, report only command names written for this
agent. Other callers receive the union of all written names.
Returns:
Command names whose skill output was successfully written.
"""
if not command_names:
return set()
# Preset-owned command names are not filtered by the
# ``speckit.<ns>.<cmd>`` shape here either: a self-contained preset
# command renders its skill whether or not a like-named extension is
# installed. The per-name loop below skips anything that doesn't
# resolve to a managed skill directory.
resolver = PresetResolver(self.project_root)
active_skills_dir = self._get_skills_dir()
from .. import load_init_options
init_opts = load_init_options(self.project_root)
active_ai = init_opts.get("ai") if isinstance(init_opts, dict) else None
if not isinstance(active_ai, str) or not active_ai:
active_ai = None
# Cache registry once to avoid repeated filesystem reads
presets_by_priority = list(self.registry.list_by_priority())
# Group command names by winning preset to batch _register_skills calls
# while only registering skills for the specific commands being
# reconciled. This resolution (which preset/content wins) is
# directory-independent, so it's computed once and then applied to
# every affected directory below.
preset_cmds: Dict[str, List[str]] = {}
non_preset_skills: List[tuple] = []
managed_skill_names: set = set()
reconciled_skill_commands: set[str] = set()
for cmd_name in command_names:
layers = resolver.collect_all_layers(cmd_name, "command")
if not layers:
continue
skill_name, legacy_skill_name = self._skill_names_for_command(
cmd_name
)
candidate_skill_names = {skill_name, legacy_skill_name}
# Track whether any preset previously registered this skill
# (i.e., it was actively managed), so a not-yet-existing skill
# dir can be re-created per affected directory below.
for _pid, meta in presets_by_priority:
if not isinstance(meta, dict):
continue
recorded = meta.get("registered_skills", [])
if isinstance(recorded, dict):
recorded_names = {
name
for names in recorded.values()
if isinstance(names, list)
for name in names
}
elif isinstance(recorded, list):
recorded_names = set(recorded)
else:
recorded_names = set()
recorded_candidates = (
candidate_skill_names & recorded_names
)
if recorded_candidates:
managed_skill_names.update(recorded_candidates)
top_path = layers[0]["path"]
# Find the preset that owns the winning layer
found_preset = False
for pack_id, _meta in presets_by_priority:
pack_dir = self.presets_dir / pack_id
if top_path.is_relative_to(pack_dir):
preset_cmds.setdefault(pack_id, []).append(cmd_name)
found_preset = True
break
if not found_preset:
# Winner is a non-preset source (core/extension/override).
# Track the winning layer path for skill restoration.
non_preset_skills.append((skill_name, cmd_name, layers[0]))
core_ext_skills = [s for s in non_preset_skills if s[2]["source"] != "project override"]
override_skills = [s for s in non_preset_skills if s[2]["source"] == "project override"]
def apply_to_dir(
skills_dir: Path,
dir_agent: Optional[str],
*,
is_active: bool,
managed_names: Optional[Set[str]] = None,
) -> None:
dir_managed_names = (
managed_skill_names if managed_names is None else managed_names
)
# Restore skills for commands whose winner is non-preset.
# _unregister_skills_in_dir can rmtree the skill dir, so
# overrides must be handled directly (create dir + write)
# without that call.
dir_core_ext_names = [
candidate
for _skill_name, cmd_name, _top_layer in core_ext_skills
for candidate in self._skill_names_for_command(cmd_name)
if candidate in dir_managed_names
]
if dir_core_ext_names:
self._unregister_skills_in_dir(
dir_core_ext_names,
skills_dir,
dir_agent,
restore_from_bundled_core=True,
)
for _skill_name, cmd_name, top_layer in override_skills:
target_skill_names = [
name
for name in self._skill_names_for_command(cmd_name)
if name in dir_managed_names
]
if not target_skill_names:
continue
try:
from .. import SKILL_DESCRIPTIONS
from ..shared_infra import _write_shared_text
registrar = self._command_registrar()
content = top_layer["path"].read_text(encoding="utf-8")
fm, body = registrar.parse_frontmatter(content)
short_name = cmd_name
if short_name.startswith("speckit."):
short_name = short_name[len("speckit."):]
desc = fm.get("description", "") or SKILL_DESCRIPTIONS.get(
short_name.replace(".", "-"),
f"Command: {short_name}",
)
selected_ai = dir_agent if isinstance(dir_agent, str) else ""
if selected_ai:
body = registrar.resolve_skill_placeholders(
selected_ai, fm, body, self.project_root
)
body = self._resolve_skill_command_refs(
body, registrar, selected_ai, self.project_root
)
from ..integrations import get_integration
integration = get_integration(selected_ai) if selected_ai else None
skill_title = self._skill_title_from_command(cmd_name)
wrote_override = False
for target_skill_name in target_skill_names:
skill_subdir = skills_dir / target_skill_name
# Same symlink guard as _register_skills's
# registration path (#2948).
if not self._validate_skill_subdir(
skill_subdir,
create=True,
skills_root=skills_dir,
):
continue
fm_data = registrar.build_skill_frontmatter(
selected_ai,
target_skill_name,
desc,
f"override:{cmd_name}",
)
registrar.apply_argument_hint(
fm, fm_data, integration
)
fm_text = dump_frontmatter(fm_data)
skill_content = (
f"---\n{fm_text}\n---\n\n"
f"# Speckit {skill_title} Skill\n\n{body}\n"
)
if integration is not None and hasattr(
integration, "post_process_skill_content"
):
skill_content = (
integration.post_process_skill_content(
skill_content
)
)
_write_shared_text(
skills_dir,
skill_subdir / "SKILL.md",
skill_content,
)
wrote_override = True
if (
wrote_override
and (
target_agent is None
or dir_agent == target_agent
)
):
reconciled_skill_commands.add(cmd_name)
except Exception:
pass # best-effort override skill restoration
# Register skills only for the specific commands being
# reconciled, not all commands in each winning preset's
# manifest.
for pack_id, cmds in preset_cmds.items():
dir_cmds = [
cmd
for cmd in cmds
if any(
name in dir_managed_names
for name in self._skill_names_for_command(cmd)
)
]
if not dir_cmds:
continue
pack_dir = self.presets_dir / pack_id
manifest_path = pack_dir / "preset.yml"
if not manifest_path.exists():
continue
try:
manifest = PresetManifest(manifest_path)
except PresetValidationError:
continue
cmds_set = set(dir_cmds)
filtered_manifest = self._FilteredManifest(manifest, cmds_set)
# Not dead code: _register_skills only *overwrites* skill
# subdirectories that already exist (plus brand-new ones for
# the active ai_skills agent). For a restore into a
# historical directory, _unregister_skills has just deleted
# the retiring preset's subdirectory, so pre-create the
# tracked (dir_managed_names) subdirectories here β under
# the same symlink guard β or the surviving preset's
# override would be silently skipped (#2948).
for cmd_name in dir_cmds:
for skill_name in self._skill_names_for_command(cmd_name):
if skill_name not in dir_managed_names:
continue
skill_subdir = skills_dir / skill_name
if not self._validate_skill_subdir(
skill_subdir,
create=True,
skills_root=skills_dir,
):
continue
if is_active:
# Preserve exact prior behaviour for the currently
# active directory (including the ability to create
# brand-new skill subdirectories when ai_skills is on).
written = self._register_skills(filtered_manifest, pack_dir)
else:
written = self._register_skills(
filtered_manifest, pack_dir,
target_dir=skills_dir, target_agent=dir_agent or "",
)
if target_agent is None:
written_names = {
name
for names in written.values()
for name in names
}
else:
written_names = set(written.get(target_agent, []))
for cmd_name in dir_cmds:
if written_names.intersection(
self._skill_names_for_command(cmd_name)
):
reconciled_skill_commands.add(cmd_name)
# The winning preset may not have previously written to
# this directory's agent (most notably a historical agent
# reconciliation just restored content into via
# extra_skills_dirs). If that write isn't merged back into
# the preset's own registered_skills, its registry entry
# silently lies about which directories it owns and a
# later removal of this same preset orphans the directory
# reconciliation just wrote to on its behalf (#2948).
self._merge_pack_registered_skills(pack_id, written)
extra_dirs = extra_skills_dirs or {}
if active_skills_dir:
active_provenance = extra_dirs.get(active_skills_dir)
if extra_skills_dirs is None or active_provenance:
apply_to_dir(
active_skills_dir,
active_ai,
is_active=True,
managed_names=(
set(active_provenance[1])
if active_provenance
else None
),
)
for extra_dir, (extra_agent, extra_names) in extra_dirs.items():
if extra_dir == active_skills_dir:
continue # already reconciled above as the active directory
apply_to_dir(
extra_dir,
extra_agent,
is_active=False,
managed_names=set(extra_names),
)
return reconciled_skill_commands
def _resolve_agent_skills_dir(self, agent_name: str) -> Path:
"""Resolve the real skill output directory for an integration."""
from .. import _get_skills_dir as _project_skills_dir
registrar = self._command_registrar()
agent_config = registrar.AGENT_CONFIGS.get(agent_name)
if agent_config and agent_config.get("extension") == "/SKILL.md":
return registrar._resolve_agent_dir(
agent_name, agent_config, self.project_root
)
return _project_skills_dir(self.project_root, agent_name)
def _skills_validation_root(self, skills_dir: Path) -> Optional[Path]:
"""Return the trusted root containing a project or user skill dir."""
for root in (self.project_root, Path.home()):
if skills_dir.is_relative_to(root):
return root
return None
@project_registration
def _get_skills_dir(self) -> Optional[Path]:
"""Return the active skills directory for preset skill overrides.
Uses :func:`resolve_active_skills_dir` for activation/detection,
then resolves native skill agents through the registrar's output
directory so integrations such as Hermes write to their global
skills path rather than their project-local detection marker.
Returns ``None`` (instead of raising) when the directory cannot
be created due to symlink, containment, or permission issues so
that callers can fall back gracefully.
"""
from .. import (
_print_cli_warning,
load_init_options,
resolve_active_skills_dir,
)
from ..shared_infra import _ensure_safe_shared_directory
opts = load_init_options(self.project_root)
if isinstance(opts, dict) and opts.get("ai") == "generic":
return None
try:
skills_dir = resolve_active_skills_dir(self.project_root)
except (ValueError, OSError) as exc:
_print_cli_warning(
"resolve", "skills directory", None, exc,
continuing="Continuing without skill registration.",
)
return None
if skills_dir is None:
return None
selected_ai = opts.get("ai") if isinstance(opts, dict) else None
if not isinstance(selected_ai, str) or not selected_ai:
return skills_dir
agent_skills_dir = self._resolve_agent_skills_dir(selected_ai)
if agent_skills_dir == skills_dir:
return skills_dir
validation_root = self._skills_validation_root(agent_skills_dir)
if validation_root is None:
_print_cli_warning(
"resolve",
"skills directory",
str(agent_skills_dir),
ValueError("skills directory is outside trusted roots"),
continuing="Continuing without skill registration.",
)
return None
try:
_ensure_safe_shared_directory(
validation_root,
agent_skills_dir,
context="preset skills directory",
)
except (ValueError, OSError) as exc:
_print_cli_warning(
"resolve", "skills directory", str(agent_skills_dir), exc,
continuing="Continuing without skill registration.",
)
return None
return agent_skills_dir
@staticmethod
def _skill_names_for_command(cmd_name: str) -> tuple[str, str]:
"""Return the modern and legacy skill directory names for a command."""
raw_short_name = cmd_name
if raw_short_name.startswith("speckit."):
raw_short_name = raw_short_name[len("speckit."):]
modern_skill_name = f"speckit-{raw_short_name.replace('.', '-')}"
legacy_skill_name = f"speckit.{raw_short_name}"
return modern_skill_name, legacy_skill_name
@staticmethod
def _skill_title_from_command(cmd_name: str) -> str:
"""Return a human-friendly title for a skill command name."""
title_name = cmd_name
if title_name.startswith("speckit."):
title_name = title_name[len("speckit."):]
return title_name.replace(".", " ").replace("-", " ").title()
@staticmethod
def _resolve_skill_command_refs(
body: str,
registrar: "CommandRegistrar",
selected_ai: str,
project_root: "Path | None" = None,
) -> str:
"""Render ``__SPECKIT_COMMAND_*__`` tokens in a skill body as invocations.
Looks up the agent's invoke separator and rewrites each
``__SPECKIT_COMMAND_<NAME>__`` placeholder into the matching
agent-native invocation -- ``/speckit-<cmd>`` or ``$speckit-<cmd>`` for
a ``-`` separator, ``/speckit.<cmd>`` for ``.``, or
``/skill:speckit-<cmd>`` for skill-colon agents (e.g. Kimi) -- the
same rendering the command layer applies via
``CommandRegistrar.register_commands()``.
For dual-layout agents (e.g. Bob) the separator depends on the
project's persisted skills state, so -- when *project_root* is provided
-- the separator is resolved from the integration via
``invoke_separator_for_mode`` rather than the single static
``AGENT_CONFIGS`` value.
"""
separator = None
if project_root is not None and isinstance(selected_ai, str):
try:
from .. import load_init_options
from ..integrations import get_integration
integration = get_integration(selected_ai)
if integration is not None:
separator = integration.invoke_separator_for_mode(
is_ai_skills_enabled(load_init_options(project_root))
)
except Exception:
separator = None
if separator is None:
separator = registrar.AGENT_CONFIGS.get(selected_ai, {}).get(
"invoke_separator", "."
)
prefix = get_invocation_prefix(selected_ai, separator == "-")
return IntegrationBase.resolve_command_refs(body, separator, prefix)
def _build_extension_skill_restore_index(self) -> Dict[str, Dict[str, Any]]:
"""Index extension-backed skill restore data by skill directory name."""
from ..extensions import ExtensionManifest, ValidationError
resolver = PresetResolver(self.project_root)
extensions_dir = self.project_root / ".specify" / "extensions"
restore_index: Dict[str, Dict[str, Any]] = {}
for _priority, ext_id, _metadata in resolver._get_all_extensions_by_priority():
ext_dir = extensions_dir / ext_id
manifest_path = ext_dir / "extension.yml"
if not manifest_path.is_file():
continue
try:
manifest = ExtensionManifest(manifest_path)
except (ValidationError, TypeError, AttributeError):
continue
ext_root = ext_dir.resolve()
for cmd_info in manifest.commands:
cmd_name = cmd_info.get("name")
cmd_file_rel = cmd_info.get("file")
if not isinstance(cmd_name, str) or not isinstance(cmd_file_rel, str):
continue
cmd_path = Path(cmd_file_rel)
if cmd_path.is_absolute():
continue
try:
source_file = (ext_root / cmd_path).resolve()
source_file.relative_to(ext_root)
except (OSError, ValueError):
continue
if not source_file.is_file():
continue
restore_info = {
"command_name": cmd_name,
"source_file": source_file,
"source": f"extension:{manifest.id}",
"author": manifest.data["extension"].get("author"),
"extension_id": manifest.id,
"extension_dir": ext_root,
}
modern_skill_name, legacy_skill_name = self._skill_names_for_command(cmd_name)
restore_index.setdefault(modern_skill_name, restore_info)
if legacy_skill_name != modern_skill_name:
restore_index.setdefault(legacy_skill_name, restore_info)
return restore_index
@project_registration
def _register_skills(
self,
manifest: "PresetManifest",
preset_dir: Path,
*,
target_dir: Optional[Path] = None,
target_agent: Optional[str] = None,
) -> Dict[str, List[str]]:
"""Generate SKILL.md files for preset command overrides.
For every command template in the preset, checks whether a
corresponding skill already exists in any detected skills
directory. If so, the skill is overwritten with content derived
from the preset's command file. This ensures that presets that
override commands also propagate to the agentskills.io skill
layer when skills mode was used during project initialisation.
Args:
manifest: Preset manifest.
preset_dir: Installed preset directory.
target_dir: Explicit skills directory to render into, instead
of resolving the currently active one. Used by
``_reconcile_skills`` to restore a surviving preset's
override into a historical (currently inactive) agent's
directory that removal of a higher-priority preset just
reverted (#2948).
target_agent: Explicit agent name to render for, paired with
``target_dir``. When set, skills are only ever restored
into already-tracked directories/names β brand-new skill
subdirectories are never created for a non-active,
explicitly targeted directory (that creation path is only
meaningful for the currently active agent).
Returns:
``{agent_name: [skill_name, ...]}`` for the single active
agent skills were written for (empty if none were written),
matching the shape ``registered_commands`` already uses so the
two can be tracked/restored consistently (#2948).
"""
command_templates = [
t for t in manifest.templates if t.get("type") == "command"
]
if not command_templates:
return {}
# Preset command templates are self-contained and render as skills
# regardless of whether a like-named extension is installed β the same
# rule _register_commands() uses. No ``speckit.<ns>.<cmd>`` name-shape
# filtering; the per-command loop below skips anything without a target
# skill directory.
skills_dir = target_dir if target_dir is not None else self._get_skills_dir()
if not skills_dir:
return {}
resolver = PresetResolver(self.project_root)
from .. import SKILL_DESCRIPTIONS, load_init_options
from ..integrations import get_integration
from ..shared_infra import _write_shared_text
init_opts = load_init_options(self.project_root)
if not isinstance(init_opts, dict):
init_opts = {}
selected_ai = target_agent if target_agent is not None else init_opts.get("ai")
if not isinstance(selected_ai, str) or not selected_ai:
return {}
# A target_dir/target_agent call reconciles an explicitly-known,
# already-tracked directory (see _reconcile_skills) rather than the
# currently active agent, so ai_skills_enabled must not be derived
# from the *current* project-wide toggle for that other agent β it
# only controls whether brand-new skill subdirectories may be
# created below, which is only meaningful for the active agent.
ai_skills_enabled = target_agent is None and is_ai_skills_enabled(init_opts)
registrar = self._command_registrar()
integration = get_integration(selected_ai)
agent_config = registrar.AGENT_CONFIGS.get(selected_ai, {})
# Native skill agents (e.g. codex/kimi/agy/trae) materialize brand-new
# preset skills in _register_commands() because their detected agent
# directory is already the skills directory. This flag is only for
# command-backed agents that also mirror commands into skills.
create_missing_skills = ai_skills_enabled and agent_config.get("extension") != "/SKILL.md"
written: List[str] = []
for cmd_tmpl in command_templates:
cmd_name = cmd_tmpl["name"]
cmd_file_rel = cmd_tmpl["file"]
source_file = preset_dir / cmd_file_rel
if not source_file.exists():
continue
# Use composed content if available (written by _register_commands
# for commands with non-replace strategies), otherwise the original.
composed_file = preset_dir / ".composed" / f"{cmd_name}.md"
if composed_file.exists():
source_file = composed_file
# Derive the short command name (e.g. "specify" from "speckit.specify")
raw_short_name = cmd_name
if raw_short_name.startswith("speckit."):
raw_short_name = raw_short_name[len("speckit."):]
short_name = raw_short_name.replace(".", "-")
skill_name, legacy_skill_name = self._skill_names_for_command(cmd_name)
skill_title = self._skill_title_from_command(cmd_name)
# Only overwrite skills that already exist under skills_dir,
# including Kimi native skills when ai_skills is false.
# If both modern and legacy directories exist, update both.
target_skill_names: List[str] = []
if (skills_dir / skill_name).is_dir():
target_skill_names.append(skill_name)
if legacy_skill_name != skill_name and (skills_dir / legacy_skill_name).is_dir():
target_skill_names.append(legacy_skill_name)
if not target_skill_names and create_missing_skills:
missing_skill_dir = skills_dir / skill_name
if not missing_skill_dir.exists():
target_skill_names.append(skill_name)
if not target_skill_names:
continue
# Parse the command file
content = source_file.read_text(encoding="utf-8")
frontmatter, body = registrar.parse_frontmatter(content)
# A composition-strategy command (wrap/prepend/append) needs a
# base layer to compose onto. When _register_commands produced no
# composed file for it and the stack still has no base
# (resolve_content is None) β e.g. the command it wraps comes from
# an extension that isn't installed β rendering the raw preset
# fragment as a skill would emit broken output: a literal
# {CORE_TEMPLATE} for wrap, or only the preset's own fragment for
# prepend/append. Skip it here too so command mode and skills mode
# agree (mirrors _register_commands, which skips the same command).
# _register_commands already warned for this command in the same
# pass, so the skip is silent here to avoid a duplicate warning.
effective_strategy = (
cmd_tmpl.get("strategy")
or frontmatter.get("strategy")
or "replace"
)
if (
effective_strategy != "replace"
and not composed_file.exists()
and resolver.resolve_content(cmd_name, "command") is None
):
continue
if frontmatter.get("strategy") == "wrap":
body, core_frontmatter = _substitute_core_template(body, cmd_name, self.project_root, registrar)
frontmatter = dict(frontmatter)
for key in ("scripts", "agent_scripts", "argument-hint"):
if key not in frontmatter and key in core_frontmatter:
frontmatter[key] = core_frontmatter[key]
original_desc = frontmatter.get("description", "")
enhanced_desc = original_desc or SKILL_DESCRIPTIONS.get(
short_name,
f"Spec-kit workflow command: {short_name}",
)
frontmatter = dict(frontmatter)
frontmatter["description"] = enhanced_desc
body = registrar.resolve_skill_placeholders(
selected_ai, frontmatter, body, self.project_root
)
body = self._resolve_skill_command_refs(body, registrar, selected_ai, self.project_root)
for target_skill_name in target_skill_names:
skill_subdir = skills_dir / target_skill_name
if skill_subdir.exists() and not skill_subdir.is_dir():
continue
# Validate (and create, if missing) the skill's own
# subdirectory under the same symlink guard as its parent β
# is_dir() above follows symlinks, so a symlinked subdir
# with a real parent would otherwise slip through and have
# SKILL.md written through it to an arbitrary location (#2948).
if not self._validate_skill_subdir(
skill_subdir, create=True, skills_root=skills_dir
):
continue
frontmatter_data = registrar.build_skill_frontmatter(
selected_ai,
target_skill_name,
enhanced_desc,
f"preset:{manifest.id}",
)
registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)
frontmatter_text = dump_frontmatter(frontmatter_data)
skill_content = (
f"---\n"
f"{frontmatter_text}\n"
f"---\n\n"
f"# Speckit {skill_title} Skill\n\n"
f"{body}\n"
)
if integration is not None and hasattr(integration, "post_process_skill_content"):
skill_content = integration.post_process_skill_content(
skill_content
)
skill_file = skill_subdir / "SKILL.md"
_write_shared_text(
skills_dir, skill_file, skill_content
)
written.append(target_skill_name)
self._merge_pack_registered_skills(
manifest.id, {selected_ai: [target_skill_name]}
)
return {selected_ai: written} if written else {}
def _infer_legacy_skill_provenance(
self, skill_names: List[str], pack_id: str, fallback_agent: str
) -> Dict[str, List[str]]:
"""Infer per-agent ownership of a legacy flat-list ``registered_skills`` value.
Pre-#2948 registries recorded ``registered_skills`` as a flat list
with no record of which agent directory each name was actually
written under. Blindly attributing every name to ``fallback_agent``
(the agent currently being processed) loses the real writer whenever
the *first* operation after upgrading is a direct switch to a
*different* agent β e.g. a legacy Copilot override (written while
Copilot was active with ``ai_skills`` enabled) followed directly by
``integration use claude``, with no intervening rescaffold for
Copilot β permanently orphaning Copilot's override on later
removal.
Every project-local configured integration's skills directory is probed (via
the same safe, symlink-validated helpers used for
restore/removal), not only agents whose registrar config is
statically ``/SKILL.md``-only: a command-backed agent (e.g.
Copilot, whose command extension is ``.agent.md``) renders its
preset overrides as ``SKILL.md`` files exactly like a native
skill-only agent whenever it was the active agent with
``ai_skills`` enabled, so excluding it would miss real,
preset-owned provenance and misattribute it to whichever agent
happens to be processed first. Each directory is probed for a
``SKILL.md`` whose frontmatter records this exact preset as the
owner (``metadata.source == "preset:<pack_id>"``, the same marker
:meth:`_register_skills` writes) β this marker check is what keeps
the broadened probe from falsely attributing ownership to an
agent's directory that never actually held this preset's override
(e.g. a command-mode agent that never rendered skills, or an
unrelated skill of the same name). A name can legitimately be
found under more than one agent's directory β the preset may have
been active while the user switched between several agents before
provenance tracking existed β so every matching agent is recorded,
not just the first. Names that can't be matched to any directory
(e.g. the file was deleted out of band) fall back to
``fallback_agent``, preserving the previous best-effort behaviour
for the unrecoverable case.
"""
registrar = self._command_registrar()
candidate_agents = sorted(registrar.AGENT_CONFIGS)
# Multiple agent names can resolve to the same physical directory
# (e.g. agy/amp/codex/zed all use .agents/skills); group by
# directory so each is probed once and attributed to a single
# deterministic canonical agent name, matching the tie-break
# already used by _unregister_skills's directory grouping. Deliberately
# keep the unresolved path (matching what _safe_skills_dir_for_agent
# already validated) rather than calling .resolve() here: on macOS
# /var is itself a symlink to /private/var, so resolving would make
# this path diverge from self.project_root's own resolution state
# and make every subsequent containment check in
# _validate_skill_subdir() spuriously fail.
dir_to_agents: Dict[Path, List[str]] = {}
for agent_name in candidate_agents:
skills_dir = self._safe_skills_dir_for_agent(agent_name)
if skills_dir is None:
continue
# Only project-local skills directories are eligible: the
# legacy provenance markers don't record which project owns a
# skill under a home directory, so deletion stays restricted
# to the project root. Revisit if provenance ever records the
# owning project.
if not Path(os.path.abspath(skills_dir)).is_relative_to(
Path(os.path.abspath(self.project_root))
):
continue
dir_to_agents.setdefault(skills_dir, []).append(agent_name)
marker = f"preset:{pack_id}"
# Filter unsafe names once, up front, rather than only inside the
# matching loop: any name skipped there would otherwise still
# land in "unmatched" below and get blindly attributed to
# fallback_agent anyway, defeating the guard entirely (#2948).
safe_skill_names = [
name for name in skill_names if self._is_safe_registry_skill_name(name)
]
inferred: Dict[str, List[str]] = {}
matched_names: set = set()
for resolved_dir, agents in dir_to_agents.items():
canonical_agent = fallback_agent if fallback_agent in agents else sorted(agents)[0]
for name in safe_skill_names:
skill_subdir = resolved_dir / name
if not self._validate_skill_subdir(
skill_subdir, create=False, skills_root=resolved_dir
):
continue
skill_file = skill_subdir / "SKILL.md"
if not skill_file.is_file():
continue
try:
content = skill_file.read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError):
continue
frontmatter, _ = registrar.parse_frontmatter(content)
skill_metadata = frontmatter.get("metadata")
source = (
skill_metadata.get("source")
if isinstance(skill_metadata, dict)
else None
)
if source == marker:
inferred.setdefault(canonical_agent, []).append(name)
matched_names.add(name)
unmatched = [name for name in safe_skill_names if name not in matched_names]
if unmatched and fallback_agent:
fallback_names = inferred.setdefault(fallback_agent, [])
for name in unmatched:
if name not in fallback_names:
fallback_names.append(name)
return inferred
@staticmethod
def _normalize_registered_skills(
value: Any, fallback_agent: Optional[str] = None
) -> Dict[str, List[str]]:
"""Normalize a ``registered_skills`` registry value to per-agent form.
The registry stores ``registered_skills`` as ``Dict[str, List[str]]``
(agent name -> skill names actually written for that agent),
mirroring ``registered_commands``. Older registries predate that
provenance and stored a flat ``List[str]`` with no record of which
agent directory the names were written under; since that can't be
recovered, ``fallback_agent`` (when given) attributes the legacy
list to the agent currently being processed so the format
self-migrates on the next write. Without a fallback agent, legacy
lists are dropped rather than guessed at.
Callers that can identify the owning preset (i.e. have a
``pack_id``) should prefer :meth:`_infer_legacy_skill_provenance`
for a legacy flat-list value instead, which probes on-disk
provenance rather than assuming ``fallback_agent`` wrote every name.
"""
if isinstance(value, dict):
return {
agent: list(names)
for agent, names in value.items()
if isinstance(agent, str) and isinstance(names, list)
}
if isinstance(value, list) and value and fallback_agent:
return {fallback_agent: [n for n in value if isinstance(n, str)]}
return {}
def _safe_skills_dir_for_agent(self, agent_name: str) -> Optional[Path]:
"""Resolve ``agent_name``'s skills directory, validated for safety.
Unlike :meth:`_get_skills_dir` (which resolves only the *currently
active* integration via init-options), this resolves an arbitrary
agent's directory from persisted provenance so a preset's skill
registrations can be restored/cleaned up under an agent that isn't
currently active. The candidate directory is validated through the
project's shared symlink/containment guard before any file in it is
touched; directories that don't exist or fail validation are
skipped rather than raising.
"""
from ..shared_infra import _ensure_safe_shared_directory
if agent_name not in self._command_registrar().AGENT_CONFIGS:
return None
skills_dir = self._resolve_agent_skills_dir(agent_name)
validation_root = self._skills_validation_root(skills_dir)
if validation_root is None:
return None
try:
_ensure_safe_shared_directory(
validation_root, skills_dir,
create=False, context="preset skills directory",
)
except (ValueError, OSError):
return None
return skills_dir
@staticmethod
def _is_safe_registry_skill_name(name: Any) -> bool:
"""Validate a registry-provided skill name is a single safe path component.
``registered_skills`` entries are persisted registry data, not
derived from the current preset manifest, so a corrupted or
maliciously edited registry could contain an absolute path, a
multi-segment path (containing ``/`` or ``\\``), or a traversal
component (``"."``/``".."``) instead of a plain skill directory
name. Any of these β if joined directly onto a skills directory β
can escape the intended skill subtree while still resolving to a
location inside the project root, which is enough to pass the
parent-directory containment/symlink check alone (#2948). This
centralizes the single boundary check every preset cleanup and
provenance loop that consumes registry-provided skill names must
apply before ever constructing a path from one.
"""
if not isinstance(name, str) or not name:
return False
if name in (".", ".."):
return False
candidate = Path(name)
if candidate.is_absolute():
return False
if len(candidate.parts) != 1:
return False
if candidate.name != name:
return False
return True
def _validate_skill_subdir(
self,
skill_subdir: Path,
*,
create: bool,
skills_root: Optional[Path] = None,
) -> bool:
"""Validate a single skill's subdirectory is symlink-free.
Unlike :meth:`_safe_skills_dir_for_agent` (which only validates the
*parent* skills directory), this validates the skill's own
subdirectory β e.g. ``.claude/skills/speckit-specify`` β so a
symlink planted at that level (with a safe parent) can't be used to
write or delete through to a location outside the project. Shared by
both the registration path (``create=True``, so a missing directory
is created component-by-component under the same guard) and the
restore/removal path (``create=False``, so a missing directory is
left for the caller's own existence check to skip). Returns
``False`` rather than raising when the path escapes the project
root or crosses a symlink. ``skills_root`` supplies the trusted
agent output boundary for native global skill integrations such as
Hermes; project-local callers default to ``self.project_root``.
"""
from ..shared_infra import (
_ensure_safe_shared_directory,
_validate_safe_shared_directory,
)
validation_root = skills_root or self.project_root
if validation_root.is_symlink():
return False
try:
if create:
_ensure_safe_shared_directory(
validation_root, skill_subdir,
create=True, context="preset skill directory",
)
else:
_validate_safe_shared_directory(
validation_root, skill_subdir
)
except (ValueError, OSError):
return False
return True
def _unregister_skills(
self,
registered_skills: Union[Dict[str, List[str]], List[str]],
preset_dir: Union[Path, str],
*,
additional_owned_sources: Optional[Dict[str, str]] = None,
restore_from_bundled_core: bool = False,
) -> Dict[Path, tuple[Optional[str], List[str]]]:
"""Restore original SKILL.md files after a preset is removed.
For each skill that was overridden by the preset, attempts to
regenerate the skill from the core command template. If no core
template exists, the skill directory is removed.
Args:
restore_from_bundled_core: When True, a missing project-local
core template (the common case β ``specify init`` never
populates ``.specify/templates/commands``) falls back to
the bundled core_pack/repo-root templates so the skill is
restored instead of deleted (#3928). Callers that are
retiring a skill because its command now renders elsewhere
(a command file superseding it) must leave this False so
the skill is removed rather than resurrected with core
content that would duplicate the winning command.
``registered_skills`` records exactly which agent directories this
preset actually wrote to (see :meth:`_register_skills`), so removal
restores precisely those directories rather than guessing at every
skill-mode agent that happens to exist on disk. Each directory is
re-resolved and safety-validated at removal time (see
:meth:`_safe_skills_dir_for_agent`) since it may belong to an agent
that isn't currently active.
Args:
registered_skills: Per-agent skill names written by the preset
(``{agent_name: [skill_name, ...]}``), or a legacy flat
``List[str]`` from a registry written before this
provenance tracking existed.
preset_dir: The preset's installed directory (may already be deleted).
additional_owned_sources: Generated non-preset source markers
that this cleanup may also replace for specific skill names.
Returns:
``{skills_dir: (renderer_agent, managed_skill_names)}`` for
every directory and skill name actually restored or removed.
"""
if not registered_skills:
return {}
pack_id = preset_dir if isinstance(preset_dir, str) else preset_dir.name
if isinstance(registered_skills, dict):
from .. import load_init_options
init_opts = load_init_options(self.project_root)
active_agent = init_opts.get("ai") if isinstance(init_opts, dict) else None
if not isinstance(active_agent, str) or not active_agent:
active_agent = None
# Multiple integration keys can share the same physical
# directory (e.g. agy/codex/zed all resolve to
# ``.agents/skills``). Restoring that directory once per
# recorded agent would have each pass's agent-specific
# rendering (frontmatter, post-processing) overwrite the
# previous one, with whichever agent is iterated *last* silently
# winning regardless of which agent is actually active. Group
# provenance by resolved directory so each physical directory is
# restored exactly once, using the active agent's renderer when
# it shares that directory (otherwise any recorded owner,
# chosen deterministically).
groups: Dict[Path, Dict[str, Any]] = {}
for agent_name, skill_names in registered_skills.items():
if not skill_names:
continue
skills_dir = self._safe_skills_dir_for_agent(agent_name)
if skills_dir is None:
continue
group = groups.setdefault(skills_dir, {"agents": [], "names": []})
group["agents"].append(agent_name)
for name in skill_names:
if (
self._is_safe_registry_skill_name(name)
and name not in group["names"]
):
group["names"].append(name)
restored: Dict[Path, tuple[Optional[str], List[str]]] = {}
for skills_dir, group in groups.items():
agents = group["agents"]
renderer_agent = (
active_agent if active_agent in agents else sorted(agents)[0]
)
mutated_names = self._unregister_skills_in_dir(
group["names"],
skills_dir,
renderer_agent,
pack_id=pack_id,
additional_owned_sources=additional_owned_sources,
restore_from_bundled_core=restore_from_bundled_core,
)
if mutated_names:
restored[skills_dir] = (
renderer_agent,
mutated_names,
)
return restored
# Legacy flat-list format: no record of which agent directory these
# names were written under, so best-effort restore is limited to the
# currently active agent's directory (the pre-provenance behaviour).
skills_dir = self._get_skills_dir()
if not skills_dir:
return {}
from .. import load_init_options
init_opts = load_init_options(self.project_root)
if not isinstance(init_opts, dict):
init_opts = {}
selected_ai = init_opts.get("ai")
selected_ai = selected_ai if isinstance(selected_ai, str) else None
safe_names = [
name
for name in registered_skills
if self._is_safe_registry_skill_name(name)
]
mutated_names = self._unregister_skills_in_dir(
safe_names,
skills_dir,
selected_ai,
pack_id=pack_id,
additional_owned_sources=additional_owned_sources,
restore_from_bundled_core=restore_from_bundled_core,
)
return (
{skills_dir: (selected_ai, mutated_names)}
if mutated_names
else {}
)
def _delete_agent_preset_skills(
self, agent_name: str, skill_names: List[str], pack_id: str
) -> None:
"""Delete still-preset-owned skills when an agent is deactivated."""
skills_dir = self._safe_skills_dir_for_agent(agent_name)
if skills_dir is None:
return
registrar = self._command_registrar()
marker = f"preset:{pack_id}"
override_sources: Dict[str, str] = {}
manifest = PresetResolver(self.project_root)._get_manifest(
self.presets_dir / pack_id
)
if manifest is not None:
for template in manifest.templates:
command_name = template.get("name")
if (
template.get("type") == "command"
and isinstance(command_name, str)
):
for skill_name in self._skill_names_for_command(
command_name
):
override_sources[skill_name] = (
f"override:{command_name}"
)
for skill_name in skill_names:
if not self._is_safe_registry_skill_name(skill_name):
continue
skill_subdir = skills_dir / skill_name
if not self._validate_skill_subdir(
skill_subdir, create=False, skills_root=skills_dir
):
continue
skill_file = skill_subdir / "SKILL.md"
if not skill_file.is_file():
continue
try:
content = skill_file.read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError):
continue
frontmatter, _ = registrar.parse_frontmatter(content)
metadata = frontmatter.get("metadata")
source = (
metadata.get("source")
if isinstance(metadata, dict)
else None
)
owned_sources = {marker}
override_source = override_sources.get(skill_name)
if override_source:
owned_sources.add(override_source)
if source in owned_sources:
from ..integrations._file_changes import after_file_change, before_file_change
before_file_change(skill_subdir, removal=True)
shutil.rmtree(skill_subdir)
after_file_change(skill_subdir)
@staticmethod
def _warn_unrestored_skill(
skill_name: str, source_file: Path, exc: BaseException
) -> None:
"""Warn that a skill kept preset content because its restore source is unreadable.
Skipping the restore is the safe recovery β the alternative branch
deletes the skill outright β but it is still a partial removal: the
preset directory and registry entry go away while this ``SKILL.md``
keeps the removed preset's content, and reconciliation never revisits
it because the name is left out of ``mutated_names``. Name the skill
and the source so the condition is actionable instead of silent.
"""
import warnings
warnings.warn(
f"Skill '{skill_name}' still contains the removed preset's content: "
f"its restore source '{source_file}' could not be read "
f"({exc.__class__.__name__}: {exc}). The skill was left in place "
f"rather than deleted. Fix or remove that file and re-run "
f"'specify preset add'/'specify preset remove' to refresh it.",
stacklevel=2,
)
@project_registration
def _unregister_skills_in_dir(
self,
skill_names: List[str],
skills_dir: Path,
selected_ai: Optional[str],
*,
pack_id: Optional[str] = None,
additional_owned_sources: Optional[Dict[str, str]] = None,
restore_from_bundled_core: bool = False,
) -> List[str]:
"""Restore original SKILL.md files within a single skills directory.
Args:
skill_names: List of skill names written by the preset.
skills_dir: The skills directory to restore within.
selected_ai: The agent name that owns ``skills_dir``, used for
placeholder resolution and argument-hint formatting.
additional_owned_sources: Generated non-preset source markers
accepted as owned for specific skill names.
restore_from_bundled_core: See ``_unregister_skills``.
Returns:
Skill names whose files were restored or removed.
"""
from .. import SKILL_DESCRIPTIONS
from ..integrations import get_integration
from ..shared_infra import _write_shared_text
# Locate core command templates from the project's installed templates
core_templates_dir = self.project_root / ".specify" / "templates" / "commands"
registrar = self._command_registrar()
integration = get_integration(selected_ai) if isinstance(selected_ai, str) else None
extension_restore_index = self._build_extension_skill_restore_index()
mutated_names: List[str] = []
for skill_name in skill_names:
# Guard against a corrupted/malicious registry entry: a
# registered_skills name is persisted data, not derived from
# the current manifest, so it must be validated as a single,
# relative, non-"."/".." path component before ever being
# joined onto skills_dir. Without this, an absolute name
# discards skills_dir entirely (Path's "/" operator drops the
# left side for an absolute right side) or a multi-component
# name containing ".." can resolve to a different, unrelated
# directory that still happens to be inside the project root
# β passing the containment-only symlink guard below and
# letting removal overwrite/delete it (#2948).
if not self._is_safe_registry_skill_name(skill_name):
continue
# Derive command name from skill name (speckit-specify -> specify)
short_name = skill_name
if short_name.startswith("speckit-"):
short_name = short_name[len("speckit-"):]
elif short_name.startswith("speckit."):
short_name = short_name[len("speckit."):]
skill_subdir = skills_dir / skill_name
skill_file = skill_subdir / "SKILL.md"
if not skill_subdir.is_dir():
continue
# is_dir() follows symlinks, so a symlinked skill subdirectory
# (with a safe, non-symlinked parent) would otherwise slip past
# _safe_skills_dir_for_agent's parent-only check and have
# write_text/rmtree operate through it (#2948).
if not self._validate_skill_subdir(
skill_subdir, create=False, skills_root=skills_dir
):
continue
if not skill_file.is_file():
# Only manage directories that contain the expected skill entrypoint.
continue
if pack_id is not None:
try:
current_content = skill_file.read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError):
continue
current_frontmatter, _ = registrar.parse_frontmatter(current_content)
current_metadata = current_frontmatter.get("metadata")
current_source = (
current_metadata.get("source")
if isinstance(current_metadata, dict)
else None
)
owned_sources = {f"preset:{pack_id}"}
if additional_owned_sources:
additional_source = additional_owned_sources.get(
skill_name
)
if additional_source:
owned_sources.add(additional_source)
if current_source not in owned_sources:
continue
extension_restore = extension_restore_index.get(skill_name)
# Try to find the core command template. Project-local overrides
# in core_templates_dir take precedence, but that directory is
# rarely populated β the real core commands ship in the bundled
# core_pack (wheel install) or the repo-root templates/ tree
# (source checkout). Callers that want a genuine restore (a
# preset was removed outright, not superseded by another
# renderer) opt into that fallback via restore_from_bundled_core
# so the skill is restored instead of deleted (#3928). An
# installed extension providing a core-named command resolves
# ahead of bundled core elsewhere, so skip the bundled fallback
# when an extension restore exists β otherwise it would win
# over the higher-priority extension layer below.
core_file = core_templates_dir / f"{short_name}.md"
if (
not core_file.exists()
and restore_from_bundled_core
and extension_restore is None
):
from .. import _locate_core_pack, _repo_root
_core_pack = _locate_core_pack()
if _core_pack is not None:
core_file = _core_pack / "commands" / f"{short_name}.md"
else:
core_file = _repo_root() / "templates" / "commands" / f"{short_name}.md"
if not core_file.exists():
core_file = None
if core_file:
# Restore from core template. An unreadable/undecodable
# source cannot produce restored content, so leave the
# existing skill untouched rather than leaking a raw
# OSError/UnicodeDecodeError out of `preset remove` β and
# rather than falling through to the rmtree below, which
# would delete a skill precisely when its replacement
# cannot be generated. Matches the `continue` guards above
# (unsafe name, missing subdir, foreign owner), which also
# skip without recording the name as mutated.
try:
content = core_file.read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError) as exc:
self._warn_unrestored_skill(skill_name, core_file, exc)
continue
frontmatter, body = registrar.parse_frontmatter(content)
if isinstance(selected_ai, str):
body = registrar.resolve_skill_placeholders(
selected_ai, frontmatter, body, self.project_root
)
body = self._resolve_skill_command_refs(
body, registrar, selected_ai, self.project_root
)
original_desc = frontmatter.get("description", "")
enhanced_desc = original_desc or SKILL_DESCRIPTIONS.get(
short_name,
f"Spec-kit workflow command: {short_name}",
)
frontmatter_data = registrar.build_skill_frontmatter(
selected_ai if isinstance(selected_ai, str) else "",
skill_name,
enhanced_desc,
f"templates/commands/{short_name}.md",
)
registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)
frontmatter_text = dump_frontmatter(frontmatter_data)
skill_title = self._skill_title_from_command(short_name)
skill_content = (
f"---\n"
f"{frontmatter_text}\n"
f"---\n\n"
f"# Speckit {skill_title} Skill\n\n"
f"{body}\n"
)
if integration is not None and hasattr(integration, "post_process_skill_content"):
skill_content = integration.post_process_skill_content(
skill_content
)
_write_shared_text(skills_dir, skill_file, skill_content)
mutated_names.append(skill_name)
continue
if extension_restore:
# Same boundary as the core-template branch above: an
# unreadable extension source leaves the skill in place
# instead of crashing or being deleted.
try:
content = extension_restore["source_file"].read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError) as exc:
self._warn_unrestored_skill(
skill_name, extension_restore["source_file"], exc
)
continue
frontmatter, body = registrar.parse_frontmatter(content)
# Mirror the register-time rewrite (#2101): resolve
# extension-relative subdir references (agents/,
# knowledge-base/, etc.) to their installed location before
# the generic placeholder resolution below, otherwise
# restoring after a preset override removal would leave
# bare, unresolvable paths in the skill body.
body = registrar.rewrite_extension_paths(
body,
extension_restore["extension_id"],
extension_restore["extension_dir"],
)
if isinstance(selected_ai, str):
body = registrar.resolve_skill_placeholders(
selected_ai, frontmatter, body, self.project_root
)
body = self._resolve_skill_command_refs(
body, registrar, selected_ai, self.project_root
)
command_name = extension_restore["command_name"]
title_name = self._skill_title_from_command(command_name)
frontmatter_data = registrar.build_skill_frontmatter(
selected_ai if isinstance(selected_ai, str) else "",
skill_name,
frontmatter.get("description", f"Extension command: {command_name}"),
extension_restore["source"],
author=extension_restore.get("author", "github-spec-kit"),
)
registrar.apply_argument_hint(frontmatter, frontmatter_data, integration)
frontmatter_text = dump_frontmatter(frontmatter_data)
skill_content = (
f"---\n"
f"{frontmatter_text}\n"
f"---\n\n"
f"# {title_name} Skill\n\n"
f"{body}\n"
)
if integration is not None and hasattr(integration, "post_process_skill_content"):
skill_content = integration.post_process_skill_content(
skill_content
)
_write_shared_text(skills_dir, skill_file, skill_content)
mutated_names.append(skill_name)
else:
# No core or extension template β remove the skill entirely
from ..integrations._file_changes import after_file_change, before_file_change
before_file_change(skill_subdir, removal=True)
shutil.rmtree(skill_subdir)
after_file_change(skill_subdir)
mutated_names.append(skill_name)
return mutated_names