## Bug: `speckit.archive.run` command not registered in `.claude/commands/` after installation

[dhanveer]

Summary

After running specify extension add archive --from https://github.com/stn1slv/spec-kit-archive/archive/refs/tags/v1.0.0.zip, the extension installs correctly

under .specify/extensions/archive/ but the command speckit.archive.run is

never registered as a Claude Code slash command. It is completely invisible to

the user.

Steps to Reproduce

1. specify extension add archive --from https://github.com/stn1slv/spec-kit-archive/archive/refs/tags/v1.0.0.zip

2. Verify .specify/extensions/archive/commands/archive.md exists ✅

3. Verify .specify/extensions/.registry shows archive as installed ✅

4. Check .specify/extensions/.registry → "registered_commands": {} ❌

5. Check .claude/commands/ → no speckit.archive*.md file ❌

6. Open Claude Code → /speckit.archive is not available ❌

Expected Behavior

.claude/commands/[speckit.archive.md](http://speckit.archive.md/) should be created automatically, mapping

to the command defined in extension.yml → provides.commands[0]:

• name: speckit.archive.run

• file: commands/archive.md

Actual Behavior

.specify/extensions/.registry entry for archive:

"registered_commands": {}

No file is created in .claude/commands/. The command is silently unavailable.

Workaround

Manually copy .specify/extensions/archive/commands/archive.md

→ .claude/commands/[speckit.archive.md](http://speckit.archive.md/)

Suggested Fix

The specify extension add installation step should, after unpacking:

1. Read extension.yml → provides.commands[]

2. Copy each commands/<file> → .claude/commands/<name>.md

3. Populate registered_commands in .registry

Also consider adding specify extension sync to repair existing installations.

Environment

- OS: macOS Darwin 25.4.0

- spec-kit registry schema_version: "1.0"

- Extension version: 1.0.0

[stn1slv]

Thank you for the detailed report. The reproduction steps made this easy to trace.

Short version: this is not a defect in the Archive extension. The extension.yml and commands/archive.md files are valid and follow the spec-kit Extension API correctly. The empty registered_commands: {} is written by spec-kit core during specify extension add, not by the extension. I checked the spec-kit source from release v0.5.0 up to the latest v0.8.18.

What is happening

During specify extension add, spec-kit core registers the command only for an AI agent whose output directory already exists in the project. For Claude Code that directory is .claude/skills/. If that directory does not exist at the moment you run extension add, the registration for Claude is skipped. The skip is silent: no error and no warning. The result is the empty registered_commands: {} that you saw in .registry.

The installer still prints "Extension installed successfully" and lists the provided commands from the manifest, even when nothing was actually registered. That is why the failure is invisible.

One important correction about the path

In current spec-kit (every version from about v0.5.0 to the latest v0.8.18), Claude commands are registered as "skills", not as command files. The expected output is:

.claude/skills/speckit-archive-run/SKILL.md

It is not .claude/commands/speckit.archive.md. The .claude/commands/ layout belongs to older spec-kit versions (before the integrations change around v0.5.0). So the version of spec-kit you are running matters here, and the manual workaround of copying a file into .claude/commands/ may not match how your spec-kit version actually loads commands.

To help confirm your exact case, could you please share:

1. The output of specify --version.
2. The output of ls -a .claude (so we can see whether .claude/skills/ exists).
3. Whether the project was initialized for the Claude agent.

How to fix the install

1. Make sure the Claude agent is initialized in the project so that .claude/skills/ exists before you add the extension. After that, specify extension add will create .claude/skills/speckit-archive-run/SKILL.md.
2. If the extension is already installed, you can re-run registration with specify integration switch claude. This re-registers all enabled extensions for the Claude agent. As an alternative, remove the extension and add it again after .claude/skills/ exists.

After this, the command should be available in Claude Code as /speckit.archive.run.

Where the real fix belongs

The behavior of skipping registration with no warning is in spec-kit core, in the specify extension add flow. The proper fix (for example, showing a warning when no agent matched, or registering against the configured agent even when its directory is missing) belongs in the upstream project, github/spec-kit. I would recommend opening an issue there. I am happy to help cross-link it.

I will also add a short "Prerequisites" note to the README so other users initialize a target agent before installing the extension.

[stn1slv]

Update: I filed the upstream bug report in spec-kit core, since the fix belongs there:

github/spec-kit#2769

You can follow that issue to track the fix for the silent registration behavior. In the meantime, the workaround in my earlier comment still applies: make sure the Claude agent is initialized so .claude/skills/ exists, then re-add the extension or run specify integration switch claude to re-register it.

[stn1slv]

Update / correction. I reproduced this locally on spec-kit 0.8.16. The extension actually does register correctly for Claude. The command is installed as a skill at .claude/skills/speckit-archive-run/SKILL.md and is available in Claude Code as /speckit-archive-run.

An important clarification to my earlier comment: for Claude (a skills-mode agent), the command is tracked under registered_skills in .specify/extensions/.registry, not under registered_commands. So registered_commands: {} is expected and is not a sign of failure. Please check the registered_skills field and the .claude/skills/ directory rather than registered_commands and .claude/commands/.

If you still do not see the command after installing on 0.8.16 or later, the most likely cause is an older spec-kit version that used the .claude/commands/ layout. Upgrading to a current version and re-adding the extension should resolve it.

I have also narrowed the upstream issue (github/spec-kit#2769) accordingly: the real point there is the misleading empty registered_commands field and a silent per-agent skip, not an unusable command.