-
Notifications
You must be signed in to change notification settings - Fork 7.4k
fix: Extension SKILL.md files contain unresolvable relative paths to extension subdirectories #2101
Description
Summary
When an extension is installed, its commands are registered as SKILL.md files
(for agents like Kimi and Codex). Extension command bodies commonly reference
files using paths relative to the extension root — e.g.:
Read agents/control/commander.md for instructions.
Load knowledge-base/agent-scores.yaml for calibration.
Use templates/kill-report.md as output format.
After installation the extension files live at
.specify/extensions/<id>/agents/..., .specify/extensions/<id>/knowledge-base/...,
etc. But the generated SKILL.md files emit these bare relative paths verbatim.
The AI agent resolves them relative to the workspace root, where they don't
exist, so the referenced files are never found.
Reproduction
-
Install an extension that has subdirectories (
agents/,knowledge-base/,
templates/,scripts/) referenced from its command bodies (e.g.echelon). -
Inspect the generated SKILL.md:
cat .kimi/skills/speckit-echelon-run/SKILL.md | grep "agents/"Result:
Read agents/control/commander.md for instructions.Expected:
Read .specify/extensions/echelon/agents/control/commander.md for instructions.
Root cause
CommandRegistrar.render_skill_command() renders the command body without
rewriting extension-relative paths to their installed locations. The method
has no knowledge of which source directory the body came from, so it cannot
perform the substitution.
Fix
Add CommandRegistrar._rewrite_extension_paths(text, extension_id, extension_dir)
that discovers the subdirectories that exist inside the installed extension
and rewrites matching subdir/... references to .specify/extensions/<id>/subdir/....
Call it from render_skill_command() when source_dir is provided, and thread
source_dir through from register_commands().
PR forthcoming against main.
Affected agents
Any agent using the /SKILL.md extension format — currently kimi and codex.