<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-10-20-1-command-skills-use-spec-conformant-names/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-20-1-command-skills-use-spec-conformant-names/</id>
  <title>ADR: command skills use spec-conformant spec-kitty-&lt;command&gt; names, and Antigravity gets its commands as skills</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/adr/4.x/2026-10-20-1-command-skills-use-spec-conformant-names/"/>
  <summary>Command skills are renamed spec-kitty-&lt;command&gt; by one naming authority, Antigravity becomes a command-skill agent, and the home writer is scoped to configured agents.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted (2026-10-20).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-20&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (operator).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; #6475 (command skills named &lt;code dir=&quot;auto&quot;&gt;spec-kitty.&amp;#x3C;command&gt;&lt;/code&gt; are dropped by
strict Agent Skills readers), #6470 (Google Antigravity stopped reading &lt;code dir=&quot;auto&quot;&gt;.agent/workflows&lt;/code&gt;
on 2026-10-19). Mission &lt;code dir=&quot;auto&quot;&gt;command-skill-names-and-antigravity-01M5DBWT&lt;/code&gt;. Follow-ups: #6471
(slash-command file names), #3048 (global skills fan-out).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Reader:&lt;/strong&gt; a maintainer working on the command-skill installer, the upgrade migrations, the
home-folder command writer, or adding an agent harness.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Amends:&lt;/strong&gt; ADR &lt;a href=&quot;/adr/3.x/2026-04-07-1-global-slash-command-installation/&quot;&gt;2026-04-07-1&lt;/a&gt;
(global slash command installation). Its “all agents at every CLI startup” decision is replaced
by “configured slash-command agents of the current project”, and its &lt;code dir=&quot;auto&quot;&gt;antigravity&lt;/code&gt; row
(&lt;code dir=&quot;auto&quot;&gt;~/.agent/workflows/&lt;/code&gt;) is removed. The rest of that ADR stands.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Spec Kitty delivers its workflow commands to Agent Skills harnesses (Codex, Vibe, Pi, Letta)
as generated skills under the shared project root &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt;. Each skill was a folder
named &lt;code dir=&quot;auto&quot;&gt;spec-kitty.&amp;#x3C;command&gt;&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;name: spec-kitty.&amp;#x3C;command&gt;&lt;/code&gt; in its &lt;code dir=&quot;auto&quot;&gt;SKILL.md&lt;/code&gt;.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;The dot is not allowed (#6475).&lt;/strong&gt; The Agent Skills specification allows only
&lt;code dir=&quot;auto&quot;&gt;[a-z0-9-]&lt;/code&gt; in a skill &lt;code dir=&quot;auto&quot;&gt;name&lt;/code&gt;, and the folder name must equal it. VS Code/Copilot, Cursor
and OpenCode read &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; too, and drop the dotted skills without telling the
user. The reference validator &lt;code dir=&quot;auto&quot;&gt;skills-ref&lt;/code&gt; rejects them. The generated frontmatter also
carried Claude-only keys (&lt;code dir=&quot;auto&quot;&gt;user-invocable&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;argument-hint&lt;/code&gt;) at the top level, which strict
readers reject in a shared root.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Antigravity’s surface is dead (#6470).&lt;/strong&gt; Spec Kitty wrote Antigravity’s commands only as
workflow files in &lt;code dir=&quot;auto&quot;&gt;.agent/workflows/&lt;/code&gt; (project, before 3.1.2) and &lt;code dir=&quot;auto&quot;&gt;~/.agent/workflows/&lt;/code&gt;
(home folder, at every CLI start). Antigravity stopped reading that folder on 2026-10-19
and reads Agent Skills from &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt;, so its users had no working command.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The home folder was sprayed.&lt;/strong&gt; ADR 2026-04-07-1 writes command files for every
slash-command agent at every CLI start, configured or not, including outside any project.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Every command loads in every harness that reads the shared root, with no silent drop.&lt;/li&gt;
&lt;li&gt;No mutating flow deletes or rewrites a file Spec Kitty cannot prove it owns (charter: User
Customization Preservation).&lt;/li&gt;
&lt;li&gt;One authority per concern, so the name and the frontmatter cannot drift between producers.&lt;/li&gt;
&lt;li&gt;The 12 slash-command agents’ command files and their &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.&amp;#x3C;command&gt;&lt;/code&gt; invocations do
not change in this decision (#6471 owns that).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;h3 id=&quot;1-the-name-is-spec-kitty-command-produced-by-one-authority&quot;&gt;1. The name is &lt;code dir=&quot;auto&quot;&gt;spec-kitty-&amp;#x3C;command&gt;&lt;/code&gt;, produced by one authority&lt;/h3&gt;
&lt;p&gt;The canonical command-skill name is &lt;code dir=&quot;auto&quot;&gt;spec-kitty-&amp;#x3C;command&gt;&lt;/code&gt;, and its path is
&lt;code dir=&quot;auto&quot;&gt;.agents/skills/spec-kitty-&amp;#x3C;command&gt;/SKILL.md&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/skills/command_skill_names.py&lt;/code&gt;
is the only module that composes the name, the path and the invocation tokens; it is a
dependency-free leaf, and &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_command_skill_name_authority.py&lt;/code&gt; pins that
no other module composes them.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Explicit command set, never a prefix.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty-&lt;/code&gt; is shared with shipped charter skills
(for example &lt;code dir=&quot;auto&quot;&gt;spec-kitty-implement-review&lt;/code&gt;), so a path is recognised only by exact match
against the canonical command set and the manifest. A user’s own &lt;code dir=&quot;auto&quot;&gt;spec-kitty-mine/&lt;/code&gt; skill is
never reported or touched.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Uniqueness is a test-time guarantee.&lt;/strong&gt; A test checks every canonical name against the
shipped charter skills, the built-in pack skills and the retired skill names.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Clean break.&lt;/strong&gt; No alias folder keeps the dotted names installed. The dotted names are
recorded once, as legacy, in the naming authority (not in the existing retired-skill sets).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;2-invocations-are-rewritten-at-render-time-slash-files-are-unchanged&quot;&gt;2. Invocations are rewritten at render time; slash files are unchanged&lt;/h3&gt;
&lt;p&gt;Pack sources keep &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.&amp;#x3C;command&gt;&lt;/code&gt;, which is correct for the slash-command agents. The
command-skill renderer rewrites &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.&amp;#x3C;command&gt;&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;$spec-kitty.&amp;#x3C;command&gt;&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;/skill:spec-kitty.&amp;#x3C;command&gt;&lt;/code&gt; tokens of canonical commands to the skill name, keeping the sigil.
The rewrite is agent-independent, so one rendered body serves every command-skill agent. File
names (&lt;code dir=&quot;auto&quot;&gt;spec-kitty.plan.md&lt;/code&gt;), URLs and &lt;code dir=&quot;auto&quot;&gt;spec-kitty.ai&lt;/code&gt; are left alone.&lt;/p&gt;
&lt;p&gt;How a user invokes a command skill:&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Harness&lt;/th&gt;&lt;th&gt;Invocation&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-&amp;#x3C;command&gt;&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-&amp;#x3C;command&gt;&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Vibe, Letta, Antigravity&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty-&amp;#x3C;command&gt;&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;The 12 slash-command agents&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;/spec-kitty.&amp;#x3C;command&gt;&lt;/code&gt; (unchanged)&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;A pack skill expansion target &lt;code dir=&quot;auto&quot;&gt;builtin:spec-kitty.&amp;#x3C;command&gt;&lt;/code&gt; stays accepted as input and
resolves to &lt;code dir=&quot;auto&quot;&gt;spec-kitty-&amp;#x3C;command&gt;&lt;/code&gt;; error messages list the canonical names.&lt;/p&gt;
&lt;h3 id=&quot;3-every-repair-path-applies-one-legacy-rule&quot;&gt;3. Every repair path applies one legacy rule&lt;/h3&gt;
&lt;p&gt;The installer owns the rule, and every installing path runs it: &lt;code dir=&quot;auto&quot;&gt;init&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;agent config add&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;doctor skills --fix&lt;/code&gt; and the tool-surface repair.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Recorded dotted entry.&lt;/strong&gt; The file is deleted when its bytes equal the recorded hash, or
equal today’s render under the old dotted name. Its folder is removed only when it is then
empty. Edited bytes, a directory, a link or a symlinked parent are kept with a warning,
and the manifest entry is dropped.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Unrecorded dotted skill (operator ruling 2026-10-21).&lt;/strong&gt; A clone can pull an
already-migrated manifest that no longer records its local dotted folders. An unrecorded
&lt;code dir=&quot;auto&quot;&gt;spec-kitty.&amp;#x3C;command&gt;/SKILL.md&lt;/code&gt; that is byte-identical to Spec Kitty’s dotted render is
treated as owned and retired. Anything else is kept with a warning.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;User content at a canonical path (operator ruling 2026-10-20).&lt;/strong&gt; A user file with other
bytes at &lt;code dir=&quot;auto&quot;&gt;spec-kitty-&amp;#x3C;command&gt;/SKILL.md&lt;/code&gt;, or a non-empty &lt;code dir=&quot;auto&quot;&gt;spec-kitty-&amp;#x3C;command&gt;/&lt;/code&gt; folder
without &lt;code dir=&quot;auto&quot;&gt;SKILL.md&lt;/code&gt;, is skipped with a warning. The rest of the batch installs.&lt;/li&gt;
&lt;li&gt;A remove-only preparation (&lt;code dir=&quot;auto&quot;&gt;agent config remove&lt;/code&gt;) only releases the removed agents from a
legacy entry; the rule runs when the last owner is removed.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;4-the-rename-migration-is-per-clone&quot;&gt;4. The rename migration is per clone&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;4.0.0rc8_command_skill_hyphen_names&lt;/code&gt; calls the installer once per configured command-skill
agent and deletes nothing itself. It is clone-local (&lt;code dir=&quot;auto&quot;&gt;clone_local_effect = True&lt;/code&gt;): the
&lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; files are git-ignored, so a record committed by one clone must not settle
another clone’s ledger (ADR &lt;a href=&quot;/adr/4.x/2026-10-17-1-explicit-migration-ledger/&quot;&gt;2026-10-17-1&lt;/a&gt;). Its
&lt;code dir=&quot;auto&quot;&gt;apply()&lt;/code&gt; is idempotent. An unreadable manifest, an unreadable agent configuration and any
installer refusal are a success with a warning that names &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor skills&lt;/code&gt;, because
a failed record would block later migrations and the upgrade’s surface repair retries. Every
dotted path still on disk afterwards is named in a warning. &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; prints the new
invocation names once, when the rename did something.&lt;/p&gt;
&lt;h3 id=&quot;5-doctor-skills-reports-leftovers-and-collisions&quot;&gt;5. &lt;code dir=&quot;auto&quot;&gt;doctor skills&lt;/code&gt; reports leftovers and collisions&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor skills&lt;/code&gt; reports read-only and never deletes a path it lists.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Kept edited dotted skill&lt;/strong&gt; (no longer in the manifest): a warning with the remedy
“remove it when you no longer need your edits”. The exit code stays 0 when nothing else is
wrong; keeping it is the user’s choice.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Dotted skill the manifest still records&lt;/strong&gt;, or an unrecorded one that is Spec Kitty’s exact
render: a failure (exit 1) with the remedy &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor skills --fix&lt;/code&gt;, which retires it.
A recorded one is labelled “still recorded by Spec Kitty”, whether or not it was edited:
&lt;code dir=&quot;auto&quot;&gt;--fix&lt;/code&gt; applies the legacy rule, so an edited copy is kept and released, and is then
reported as a kept edited dotted skill.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Collision at a canonical path&lt;/strong&gt;: a failure (exit 1). The command skill is not installed
until the user renames or removes the folder and runs &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor skills --fix&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;doctor skills --json&lt;/code&gt; gains two additive keys, &lt;code dir=&quot;auto&quot;&gt;legacy&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;collisions&lt;/code&gt;; no existing key
changes.&lt;/p&gt;
&lt;h3 id=&quot;6-antigravity-is-a-command-skill-agent&quot;&gt;6. Antigravity is a command-skill agent&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;antigravity&lt;/code&gt; joins &lt;code dir=&quot;auto&quot;&gt;SUPPORTED_AGENTS&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;skills/_agent_roster.py&lt;/code&gt;. Its &lt;code dir=&quot;auto&quot;&gt;AGENT_COMMAND_CONFIG&lt;/code&gt;
row and its &lt;code dir=&quot;auto&quot;&gt;.agent/workflows&lt;/code&gt; entries in &lt;code dir=&quot;auto&quot;&gt;AGENT_DIRS&lt;/code&gt; are removed. &lt;code dir=&quot;auto&quot;&gt;init&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;agent config add antigravity&lt;/code&gt; install the 14 command skills into &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt;.
&lt;code dir=&quot;auto&quot;&gt;core.config.configured_slash_agents()&lt;/code&gt; splits a configured agent list into its slash-command
half; single-key checks test membership in &lt;code dir=&quot;auto&quot;&gt;AGENT_COMMAND_CONFIG&lt;/code&gt;, the same rule.&lt;/p&gt;
&lt;p&gt;Removing the &lt;code dir=&quot;auto&quot;&gt;.agent/workflows&lt;/code&gt; entries from &lt;code dir=&quot;auto&quot;&gt;AGENT_DIRS&lt;/code&gt; also changes the historical
migrations that iterate &lt;code dir=&quot;auto&quot;&gt;get_agent_dirs_for_project()&lt;/code&gt;: they no longer visit
&lt;code dir=&quot;auto&quot;&gt;.agent/workflows&lt;/code&gt;. That is intended. Those files are dead (Antigravity stopped reading them),
and the one step that still has to handle them is &lt;code dir=&quot;auto&quot;&gt;4.0.0rc8_retire_antigravity_workflows&lt;/code&gt;,
which reaches the retired path directly (section 7). The frozen migrations are not edited.&lt;/p&gt;
&lt;h3 id=&quot;7-antigravity-workflow-files-are-archived-not-deleted&quot;&gt;7. Antigravity workflow files are archived, not deleted&lt;/h3&gt;
&lt;p&gt;Operator ruling 2026-10-20: archive, never delete.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Project.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;4.0.0rc8_retire_antigravity_workflows&lt;/code&gt; (clone-local, ordered after the rename)
archives a &lt;code dir=&quot;auto&quot;&gt;.agent/workflows/spec-kitty.&amp;#x3C;command&gt;.md&lt;/code&gt; file only when it is a regular file,
names a historical Spec Kitty command and carries an exact
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;!-- spec-kitty-command-version: X --&gt;&lt;/code&gt; line in its first 20 lines. Each proven file is
copied into its own fresh folder,
&lt;code dir=&quot;auto&quot;&gt;.kittify/backups/antigravity-workflows/.backup-&amp;#x3C;timestamp&gt;[-n]/.agent/workflows/&amp;#x3C;name&gt;&lt;/code&gt;,
and only then removed. A backup is never overwritten. Other files, unproven &lt;code dir=&quot;auto&quot;&gt;spec-kitty.*&lt;/code&gt;
names and the &lt;code dir=&quot;auto&quot;&gt;.agent/&lt;/code&gt; folders stay; a symlinked or non-directory path component refuses
with a warning. When Antigravity is configured, the migration installs its command skills in
the same step. This migration gates on the configured agents and the hard-coded retired
path, because &lt;code dir=&quot;auto&quot;&gt;.agent/workflows&lt;/code&gt; is no longer in &lt;code dir=&quot;auto&quot;&gt;AGENT_DIRS&lt;/code&gt; (a recorded deviation from
the “iterate &lt;code dir=&quot;auto&quot;&gt;get_agent_dirs_for_project()&lt;/code&gt;” rule).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Home folder.&lt;/strong&gt; The home-folder writer removes a &lt;code dir=&quot;auto&quot;&gt;~/.agent/workflows/spec-kitty.*.md&lt;/code&gt; file
only when its inventory records it unedited, or, with no record, when it carries the current
version marker and equals the frozen render byte for byte. A symlinked &lt;code dir=&quot;auto&quot;&gt;~/.agent&lt;/code&gt; or
&lt;code dir=&quot;auto&quot;&gt;~/.agent/workflows&lt;/code&gt; refuses. The folder itself is never removed.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The two proofs differ on purpose. The project copy can be committed, shared and edited by a
team, so its proof is a marker check and the file is archived, never deleted. The home copy
belongs to one person and Spec Kitty’s own inventory records what it wrote there, so its proof
is the inventory record (or an exact byte match with the frozen render) and an unedited file is
removed without a backup. Both refuse on a symlinked path component and both keep the folders.&lt;/p&gt;
&lt;h3 id=&quot;8-the-home-folder-writer-is-scoped-to-configured-agents-amends-2026-04-07-1&quot;&gt;8. The home-folder writer is scoped to configured agents (amends 2026-04-07-1)&lt;/h3&gt;
&lt;p&gt;At CLI startup, &lt;code dir=&quot;auto&quot;&gt;ensure_global_agent_commands()&lt;/code&gt; writes command files only for the
slash-command agents configured in the current project’s &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;. Outside a
project, or with no or an unreadable configuration, it writes nothing. &lt;code dir=&quot;auto&quot;&gt;agent config add&lt;/code&gt;
writes the added slash-command agents’ home files at once; a failure there is a warning and
the next CLI run retries.&lt;/p&gt;
&lt;p&gt;The freshness stamp is per key (schema 2: &lt;code dir=&quot;auto&quot;&gt;cli_version&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;template_source_signature&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;healthy_keys&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;retired_surfaces_cleaned&lt;/code&gt;). A call is fresh when every requested key is
healthy at this version and signature, so the warm startup path checks only the configured
agents. A stamp without schema 2 reads as absent, so the first run on new code builds once and
runs the &lt;code dir=&quot;auto&quot;&gt;~/.agent/workflows&lt;/code&gt; cleanup.&lt;/p&gt;
&lt;h3 id=&quot;9-frontmatter-is-projected-per-root&quot;&gt;9. Frontmatter is projected per root&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/skills/skill_frontmatter.py&lt;/code&gt; is the one frontmatter authority
(&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_single_frontmatter_authority.py&lt;/code&gt;).&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Shared roots&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; and any root not listed as native) get only the
specification fields &lt;code dir=&quot;auto&quot;&gt;name&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;description&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;license&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;compatibility&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;metadata&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;allowed-tools&lt;/code&gt;. Other keys move under &lt;code dir=&quot;auto&quot;&gt;metadata&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Native roots&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;.claude/skills&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.qwen/skills&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.kilocode/skills&lt;/code&gt;) keep
&lt;code dir=&quot;auto&quot;&gt;user-invocable&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;argument-hint&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;disable-model-invocation&lt;/code&gt; at the top level.&lt;/li&gt;
&lt;li&gt;Pack skill validation and rendering enforce name ≤ 64 and description ≤ 1024 characters at
load and again at preparation; a refusal names the limit and the length.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;10-the-reference-validator-runs-in-ci&quot;&gt;10. The reference validator runs in CI&lt;/h3&gt;
&lt;p&gt;The always-on &lt;code dir=&quot;auto&quot;&gt;agent-skills&lt;/code&gt; job in &lt;code dir=&quot;auto&quot;&gt;ci-router.yml&lt;/code&gt; runs &lt;code dir=&quot;auto&quot;&gt;scripts/ci/validate_agent_skills.py&lt;/code&gt;.
It validates every generated and shipped skill in a shared root with &lt;code dir=&quot;auto&quot;&gt;skills-ref==0.1.1&lt;/code&gt;
(through &lt;code dir=&quot;auto&quot;&gt;uvx&lt;/code&gt;) and with the in-repo mirror; native roots are checked by the mirror only. A
violation from either validator fails the job, and validator output that cannot be read is an
environment error, never a pass.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Every command skill is spec-valid and loads in every harness that reads &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Antigravity users have working commands again.&lt;/li&gt;
&lt;li&gt;Hand-edited dotted skills and user folders survive every path, each with a named remedy.&lt;/li&gt;
&lt;li&gt;A CLI run outside a project no longer writes into the home folder.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Older CLIs cannot read the new manifest.&lt;/strong&gt; The command-skill manifest schema pattern now
admits the hyphenated form; a CLI from before this release refuses a manifest written by
this one. That covers a downgrade and a teammate on an older CLI who pulls a committed
manifest.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Commands can appear twice.&lt;/strong&gt; A harness that reads both a slash-command file and
&lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; (for example a project configured for codex and copilot) now shows each
command twice, because the skills load at last. #6471 resolves this.&lt;/li&gt;
&lt;li&gt;The global skills writer still fans out to skill roots of agents a project does not use;
#3048 tracks that.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Leftover dotted folders are visible in &lt;code dir=&quot;auto&quot;&gt;doctor skills&lt;/code&gt; until the user removes them.&lt;/li&gt;
&lt;li&gt;Pre-4.x migrations that read the dotted layout are not edited (DIRECTIVE_044); ledger
selection does not re-run them on a project they settled.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Mission artifacts: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/command-skill-names-and-antigravity-01M5DBWT/&lt;/code&gt; (spec, plan,
&lt;code dir=&quot;auto&quot;&gt;traces/design-decisions.md&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Code: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/skills/command_skill_names.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;skills/command_installer.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;skills/skill_frontmatter.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;runtime/agent_commands.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;upgrade/migrations/m_4_0_0rc8_command_skill_hyphen_names.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;upgrade/migrations/m_4_0_0rc8_retire_antigravity_workflows.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;scripts/ci/validate_agent_skills.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Upgrade note: &lt;a href=&quot;/migrations/command-skill-hyphen-names/&quot;&gt;Command skills renamed for the Agent Skills specification&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
