Skip to content

fix: Extension SKILL.md files contain unresolvable relative paths to extension subdirectories #2101

@mbachorik

Description

@mbachorik

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

  1. Install an extension that has subdirectories (agents/, knowledge-base/,
    templates/, scripts/) referenced from its command bodies (e.g. echelon).

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions