<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/migrations/command-skill-hyphen-names/">
  <id>https://docs.spec-kitty.ai/migrations/command-skill-hyphen-names/</id>
  <title>Migration: Command Skills Renamed for the Agent Skills Specification</title>
  <updated>2026-10-21T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/migrations/command-skill-hyphen-names/"/>
  <summary>Upgrade to the spec-kitty-&lt;command&gt; skill names: new invocations per harness, kept edited copies, doctor skills remedies and the Antigravity workflows archive.</summary>
  <content type="html">&lt;h2 id=&quot;command-skills-renamed-for-the-agent-skills-specification&quot;&gt;Command skills renamed for the Agent Skills specification&lt;/h2&gt;
&lt;p&gt;Use this page when your project uses Spec Kitty through an Agent Skills harness (Codex CLI,
Mistral Vibe, Pi, Letta Code or Google Antigravity) and you upgrade to a release that names the
command skills &lt;code dir=&quot;auto&quot;&gt;spec-kitty-&amp;#x3C;command&gt;&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;what-changed&quot;&gt;What changed&lt;/h2&gt;
&lt;p&gt;Spec Kitty used to generate its command skills as &lt;code dir=&quot;auto&quot;&gt;.agents/skills/spec-kitty.&amp;#x3C;command&gt;/&lt;/code&gt;. The
Agent Skills specification allows only lowercase letters, digits and hyphens in a skill name,
so several harnesses that read &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; dropped those skills without a message. The
skills are now &lt;code dir=&quot;auto&quot;&gt;.agents/skills/spec-kitty-&amp;#x3C;command&gt;/&lt;/code&gt;, and their frontmatter carries only
specification fields.&lt;/p&gt;
&lt;p&gt;Google Antigravity stopped reading &lt;code dir=&quot;auto&quot;&gt;.agent/workflows/&lt;/code&gt; on 2026-10-19. Spec Kitty now delivers
Antigravity’s commands as the same &lt;code dir=&quot;auto&quot;&gt;.agents/skills/spec-kitty-&amp;#x3C;command&gt;/&lt;/code&gt; skills.&lt;/p&gt;
&lt;p&gt;The 12 slash-command agents (Claude Code, Copilot, Gemini and the others) are not affected:
their command files and &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.&amp;#x3C;command&gt;&lt;/code&gt; invocations stay as they were.&lt;/p&gt;
&lt;h2 id=&quot;how-to-invoke-a-command-now&quot;&gt;How to invoke a command now&lt;/h2&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Harness&lt;/th&gt;&lt;th&gt;Before&lt;/th&gt;&lt;th&gt;Now&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Codex CLI&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;$spec-kitty.specify&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;$spec-kitty-specify&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Pi&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;/skill:spec-kitty.specify&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;/skill:spec-kitty-specify&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Mistral Vibe, Letta Code&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty-specify&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Google Antigravity&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt; (workflow)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty-specify&lt;/code&gt; (skill)&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2 id=&quot;upgrade-your-project&quot;&gt;Upgrade your project&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;Run the upgrade in each clone of the project (the rename is recorded per clone, because
&lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; is not committed):&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upgrade&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The output lists the new invocation names when the rename did something.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Check what was left behind:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doctor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;skills&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Restart your harness, or refresh its skills, so it picks up the new names.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;what-happens-to-your-existing-dotted-skills&quot;&gt;What happens to your existing dotted skills&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Unedited copies&lt;/strong&gt; are removed and replaced by the new skills. A folder is removed only when
it is empty afterwards.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Copies you edited&lt;/strong&gt; are kept where they are, with a warning. Spec Kitty no longer manages
them. Copy your edits to wherever you want them, then delete the old folder.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Your own folder at a new name&lt;/strong&gt; (for example a &lt;code dir=&quot;auto&quot;&gt;spec-kitty-plan/&lt;/code&gt; you wrote yourself) is
not overwritten. That one command skill is skipped with a warning; the others install.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;doctor-skills-messages-and-what-to-do&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;doctor skills&lt;/code&gt; messages and what to do&lt;/h2&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Message&lt;/th&gt;&lt;th&gt;Exit code&lt;/th&gt;&lt;th&gt;What to do&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;Legacy dotted command skills (no longer managed): &amp;#x3C;path&gt; — remove it when you no longer need your edits&lt;/code&gt;&lt;/td&gt;&lt;td&gt;0 when nothing else is wrong&lt;/td&gt;&lt;td&gt;Keep it as long as you need your edits, then delete the folder.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;Legacy dotted command skill (Spec Kitty&apos;s unmodified rendering): &amp;#x3C;path&gt; — run spec-kitty doctor skills --fix to retire it&lt;/code&gt;&lt;/td&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor skills --fix&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;Legacy dotted command skill (still recorded by Spec Kitty): &amp;#x3C;path&gt; — run spec-kitty doctor skills --fix to retire it&lt;/code&gt;&lt;/td&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor skills --fix&lt;/code&gt;. An unedited copy is removed; an edited one is kept and then reported as no longer managed.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;Your own folder blocks command skill &amp;#x3C;path&gt; — rename or remove it, then run spec-kitty doctor skills --fix&lt;/code&gt;&lt;/td&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;Move your folder, then run &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor skills --fix&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;The “still recorded” message means the manifest has not been migrated yet; the check fails
until &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor skills --fix&lt;/code&gt; (or &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt;) retires the entry. &lt;code dir=&quot;auto&quot;&gt;doctor skills&lt;/code&gt; never
deletes a path it lists. &lt;code dir=&quot;auto&quot;&gt;doctor skills --json&lt;/code&gt; reports these paths under the &lt;code dir=&quot;auto&quot;&gt;legacy&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;collisions&lt;/code&gt; keys.&lt;/p&gt;
&lt;h2 id=&quot;antigravity-workflow-files&quot;&gt;Antigravity workflow files&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;In the project.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; moves each Spec Kitty-generated
&lt;code dir=&quot;auto&quot;&gt;.agent/workflows/spec-kitty.&amp;#x3C;command&gt;.md&lt;/code&gt; file into its own backup folder:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;.kittify/backups/antigravity-workflows/.backup-&amp;#x3C;timestamp&gt;/.agent/workflows/spec-kitty.&amp;#x3C;command&gt;.md&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Files Spec Kitty did not generate, and the &lt;code dir=&quot;auto&quot;&gt;.agent/&lt;/code&gt; folders themselves, stay where they are.
When Antigravity is configured, the same step installs its command skills.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;In your home folder.&lt;/strong&gt; The CLI removes the &lt;code dir=&quot;auto&quot;&gt;~/.agent/workflows/spec-kitty.*.md&lt;/code&gt; files it
wrote, when they are unedited. Edited files and the folder stay.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;home-folder-command-files&quot;&gt;Home-folder command files&lt;/h2&gt;
&lt;p&gt;The CLI now writes slash-command files into your home folder only for the slash-command agents
configured in the current project. Outside a project it writes nothing.
&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent config add &amp;#x3C;agent&gt;&lt;/code&gt; writes that agent’s files straight away.&lt;/p&gt;
&lt;h2 id=&quot;downgrading&quot;&gt;Downgrading&lt;/h2&gt;
&lt;p&gt;An older Spec Kitty CLI cannot read the command-skill manifest this release writes. If you go
back to an older CLI, or a teammate on an older CLI pulls the manifest where your project commits it, that CLI
refuses the manifest with a schema error: its schema expects the dotted skill names and does not
know the &lt;code dir=&quot;auto&quot;&gt;antigravity&lt;/code&gt; agent. Nothing is deleted; the error stops that CLI’s command-skill
commands until it is upgraded. Upgrade the older CLI instead, and ask teammates to upgrade
before you commit the migrated manifest.&lt;/p&gt;
&lt;h2 id=&quot;known-follow-ups&quot;&gt;Known follow-ups&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;In a project that combines a slash-command agent with an Agent Skills reader in the same
harness (for example codex and copilot), each command can show twice. #6471 tracks this.&lt;/li&gt;
&lt;li&gt;The global skills writer still writes skill roots for agents the project does not use. #3048
tracks this.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
