<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/development/how-to/create-a-pack-skill/">
  <id>https://docs.spec-kitty.ai/development/how-to/create-a-pack-skill/</id>
  <title>Create and activate a pack skill</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/development/how-to/create-a-pack-skill/"/>
  <summary>Author a pack skill, set its namespace, activate it into each configured tool&apos;s project skill root, and keep it healthy with doctor skills and upgrade.</summary>
  <content type="html">&lt;span id=&quot;create-and-activate-a-pack-skill&quot;&gt;&lt;/span&gt;
&lt;p&gt;A &lt;strong&gt;pack skill&lt;/strong&gt; is a short entry point your team shares through a pack, such as “draft release
notes”. Before: each person kept a private copy in their own tool. After: one reviewed
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;id&gt;.skill.yaml&lt;/code&gt; file, and every configured tool in the project gets the same skill.&lt;/p&gt;
&lt;p&gt;A pack skill is one of three things the codebase calls a “skill”. The
&lt;a href=&quot;/context/execution/#pack-skill&quot;&gt;Pack skill glossary entry&lt;/a&gt; separates it from the doctrine
skills that ship with Spec Kitty and from the generated &lt;code dir=&quot;auto&quot;&gt;spec-kitty.&amp;#x3C;command&gt;&lt;/code&gt; command skills.&lt;/p&gt;
&lt;p&gt;This page covers a &lt;strong&gt;project-tier&lt;/strong&gt; pack skill: it lives in your repository and needs no org
pack. &lt;a href=&quot;#share-the-skill-through-an-org-pack&quot;&gt;Org packs&lt;/a&gt; differ in two places, listed at the end.
For the other doctrine kinds, see &lt;a href=&quot;/development/how-to/create-a-doctrine-artifact/&quot;&gt;Create a doctrine artifact&lt;/a&gt;.&lt;/p&gt;
&lt;h2 id=&quot;prerequisites&quot;&gt;Prerequisites&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;A Spec Kitty project (&lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; has run) with at least one tool configured.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; CLI on your &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;step-1-set-the-skill-namespace&quot;&gt;Step 1: Set the skill namespace&lt;/h2&gt;
&lt;p&gt;Spec Kitty renders your skill as &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;skill_namespace&gt;-&amp;#x3C;id&gt;&lt;/code&gt;. The namespace keeps your skills apart
from the ones Spec Kitty ships. You must set it. There is no default, and Spec Kitty never
derives one from the repository name.&lt;/p&gt;
&lt;p&gt;Add this to &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;:&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;yaml&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:#7FDBCA;--1:#111111&quot;&gt;charter_packs&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;project&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;skill_namespace&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;acme&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Rules for the namespace:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Lowercase ASCII only. It starts with a letter. Letters and digits form segments, and single
&lt;code dir=&quot;auto&quot;&gt;-&lt;/code&gt; characters join the segments (&lt;code dir=&quot;auto&quot;&gt;acme&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;acme-platform&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;team2&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;At most 32 characters.&lt;/li&gt;
&lt;li&gt;Spec Kitty refuses an invalid value. It never “fixes” it for you, and it writes nothing.&lt;/li&gt;
&lt;li&gt;The prefixes &lt;code dir=&quot;auto&quot;&gt;spk-&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;spec-kitty-&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;spec-kitty.&lt;/code&gt; are reserved for built-in skills.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;If the namespace is missing, activation fails with &lt;code dir=&quot;auto&quot;&gt;project-tier skill &apos;&amp;#x3C;id&gt;&apos; has no skill namespace to render under&lt;/code&gt; and names the config key to set.&lt;/p&gt;
&lt;h2 id=&quot;step-2-write-the-skill&quot;&gt;Step 2: Write the skill&lt;/h2&gt;
&lt;p&gt;Create two files in &lt;code dir=&quot;auto&quot;&gt;.kittify/charter-packs/skills/&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/charter-packs/skills/release-notes.skill.yaml&lt;/code&gt;:&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;yaml&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:#7FDBCA;--1:#111111&quot;&gt;schema_version&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;1.0&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;id&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;release-notes&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;title&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;Draft release notes&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;description&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;Draft release notes for a release from its merged pull requests.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;triggers&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: [&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;draft release notes&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;, &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;write release notes&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;form&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;prompt&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;body_path&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;release-notes.skill.md&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;parameters&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;- &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;name&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;version&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;required&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;description&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;Release version, for example 1.4.0&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;version&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;1.0.0&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;maintainers&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: [&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;@acme/platform&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;.kittify/charter-packs/skills/release-notes.skill.md&lt;/code&gt;:&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;markdown&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;Draft release notes for the version the user names.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;1.&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; List the pull requests merged since the previous release tag.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;2.&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; Group them under Added, Changed and Fixed.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;3.&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; Write one plain sentence per pull request. Lead with what changes for the user.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;This example matches &lt;code dir=&quot;auto&quot;&gt;src/charter/offering/schemas/skill.schema.yaml&lt;/code&gt;: it has every required
field (&lt;code dir=&quot;auto&quot;&gt;schema_version&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;id&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;title&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;description&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;form&lt;/code&gt;) and &lt;code dir=&quot;auto&quot;&gt;body_path&lt;/code&gt;, which a &lt;code dir=&quot;auto&quot;&gt;prompt&lt;/code&gt;
skill requires.&lt;/p&gt;
&lt;h3 id=&quot;the-fields&quot;&gt;The fields&lt;/h3&gt;

































































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Field&lt;/th&gt;&lt;th&gt;Required&lt;/th&gt;&lt;th&gt;What it does&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;schema_version&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;Always &lt;code dir=&quot;auto&quot;&gt;&quot;1.0&quot;&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;id&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;Lowercase ASCII kebab-case: it starts with a letter and has at most 64 characters. It is the name you pass to &lt;code dir=&quot;auto&quot;&gt;charter activate&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;title&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;description&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;The heading and the description in the rendered &lt;code dir=&quot;auto&quot;&gt;SKILL.md&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;form&lt;/code&gt;&lt;/td&gt;&lt;td&gt;yes&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;prompt&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;wrapper&lt;/code&gt; (see below).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;body_path&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;prompt&lt;/code&gt; only&lt;/td&gt;&lt;td&gt;The body file, relative to the &lt;code dir=&quot;auto&quot;&gt;.skill.yaml&lt;/code&gt; file. It must stay inside that directory and have no &lt;code dir=&quot;auto&quot;&gt;..&lt;/code&gt; part; Spec Kitty enforces that with the shared containment primitive both when the skill loads and again when the body is read.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;expands_to&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;wrapper&lt;/code&gt; only&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;target&lt;/code&gt;, and optional &lt;code dir=&quot;auto&quot;&gt;args&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;triggers&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;Phrases that Spec Kitty appends to the rendered description as &lt;code dir=&quot;auto&quot;&gt;Triggers: ...&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;parameters&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;A list of &lt;code dir=&quot;auto&quot;&gt;name&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;required&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;description&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;default&lt;/code&gt;. Spec Kitty renders them as a Parameters list.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;invocation&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;user_invocable&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;model_invocable&lt;/code&gt; (both default to true) and &lt;code dir=&quot;auto&quot;&gt;side_effects&lt;/code&gt;. A non-empty &lt;code dir=&quot;auto&quot;&gt;side_effects&lt;/code&gt; list forces &lt;code dir=&quot;auto&quot;&gt;model_invocable&lt;/code&gt; to false.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;version&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;maintainers&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;Metadata for co-maintenance.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;overrides&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;enhances&lt;/code&gt;&lt;/td&gt;&lt;td&gt;no&lt;/td&gt;&lt;td&gt;Replace or narrow a skill from a lower tier. Not covered here.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;The schema also accepts &lt;code dir=&quot;auto&quot;&gt;tools&lt;/code&gt;. Spec Kitty stores it but does not use it to choose which tools
receive the skill. Every configured tool that has a project skill root receives every active
pack skill.&lt;/p&gt;
&lt;h3 id=&quot;the-two-forms&quot;&gt;The two forms&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;prompt&lt;/code&gt;&lt;/strong&gt; carries a Markdown body. Spec Kitty copies the body into &lt;code dir=&quot;auto&quot;&gt;SKILL.md&lt;/code&gt; unchanged.
It does not rewrite argument placeholders for each tool.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;wrapper&lt;/code&gt;&lt;/strong&gt; is a shorthand for an existing command. &lt;code dir=&quot;auto&quot;&gt;expands_to.target&lt;/code&gt; is either
&lt;code dir=&quot;auto&quot;&gt;builtin:spec-kitty-&amp;#x3C;command&gt;&lt;/code&gt; (one of the built-in command skills) or
&lt;code dir=&quot;auto&quot;&gt;cli:spec-kitty &amp;#x3C;arguments&gt;&lt;/code&gt;. For example:&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;yaml&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:#7FDBCA;--1:#111111&quot;&gt;form&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;wrapper&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;expands_to&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;target&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;builtin:spec-kitty-status&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;An unknown &lt;code dir=&quot;auto&quot;&gt;builtin:&lt;/code&gt; command is refused when the skill is projected, and the error lists the
known commands. The older dotted form &lt;code dir=&quot;auto&quot;&gt;builtin:spec-kitty.&amp;#x3C;command&gt;&lt;/code&gt; is still accepted and
resolves to the same command skill.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;what-requires-does&quot;&gt;What &lt;code dir=&quot;auto&quot;&gt;requires&lt;/code&gt; does&lt;/h3&gt;
&lt;p&gt;A pack skill carries no doctrine of its own. In an org pack, you declare &lt;code dir=&quot;auto&quot;&gt;requires&lt;/code&gt; as an edge in
the pack’s DRG fragment (&lt;code dir=&quot;auto&quot;&gt;drg/fragment.yaml&lt;/code&gt;):&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;yaml&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:#7FDBCA;--1:#111111&quot;&gt;edges&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;- &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;source&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;skill:land-pr&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;target&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;procedure:landing-contributor-prs&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;relation&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;requires&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 rendered &lt;code dir=&quot;auto&quot;&gt;SKILL.md&lt;/code&gt; then gets a “Governing context” section. It tells the agent to run
&lt;code dir=&quot;auto&quot;&gt;spec-kitty charter context --include &amp;#x3C;urn&gt;&lt;/code&gt; for each &lt;code dir=&quot;auto&quot;&gt;requires&lt;/code&gt; target. Spec Kitty never copies
the procedure text into the skill. Only &lt;code dir=&quot;auto&quot;&gt;requires&lt;/code&gt; edges appear there. The example above has no
edges, so its &lt;code dir=&quot;auto&quot;&gt;SKILL.md&lt;/code&gt; has no such section.&lt;/p&gt;
&lt;h3 id=&quot;what-spec-kitty-refuses&quot;&gt;What Spec Kitty refuses&lt;/h3&gt;
&lt;p&gt;For project and org skills, Spec Kitty skips the skill file with a warning (and &lt;code dir=&quot;auto&quot;&gt;doctor charter-packs&lt;/code&gt;
reports it) when:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the id or its rendered name starts with &lt;code dir=&quot;auto&quot;&gt;spk-&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;spec-kitty-&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;spec-kitty.&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;the rendered name (namespace plus id) is longer than 64 characters, or the rendered
description (with its triggers) is longer than 1024 characters (the Agent Skills limits); the
message names the limit and the length;&lt;/li&gt;
&lt;li&gt;a &lt;code dir=&quot;auto&quot;&gt;scripts/&lt;/code&gt; directory sits beside the skill file;&lt;/li&gt;
&lt;li&gt;the body frontmatter has an &lt;code dir=&quot;auto&quot;&gt;allowed-tools&lt;/code&gt; (or &lt;code dir=&quot;auto&quot;&gt;allowed_tools&lt;/code&gt;) key;&lt;/li&gt;
&lt;li&gt;the body file is missing, or &lt;code dir=&quot;auto&quot;&gt;body_path&lt;/code&gt; points outside the skill’s directory;&lt;/li&gt;
&lt;li&gt;a &lt;code dir=&quot;auto&quot;&gt;cli:&lt;/code&gt; target, or its &lt;code dir=&quot;auto&quot;&gt;args&lt;/code&gt;, contains a shell metacharacter (&lt;code dir=&quot;auto&quot;&gt;;&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;&amp;#x26;&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;|&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;&gt;&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;$&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;`&lt;/code&gt; or a line break), or the target does not start with &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt;. Because &lt;code dir=&quot;auto&quot;&gt;$&lt;/code&gt; is on that
list, a &lt;code dir=&quot;auto&quot;&gt;cli:&lt;/code&gt; wrapper cannot pass &lt;code dir=&quot;auto&quot;&gt;$ARGUMENTS&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Projection refuses, and writes no skill file, when:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;two active skills render to the same name;&lt;/li&gt;
&lt;li&gt;a skill renders under the name of a built-in skill;&lt;/li&gt;
&lt;li&gt;the namespace is invalid or missing;&lt;/li&gt;
&lt;li&gt;a skill is installed or listed in &lt;code dir=&quot;auto&quot;&gt;activated_skills&lt;/code&gt;, and a configured org pack is not fetched or its
&lt;code dir=&quot;auto&quot;&gt;org-charter.yaml&lt;/code&gt; cannot be read (run &lt;code dir=&quot;auto&quot;&gt;spec-kitty charter fetch --pack &amp;#x3C;name&gt;&lt;/code&gt; or fix the file).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;To see the skipped files, run &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor charter-packs --json&lt;/code&gt; and read
&lt;code dir=&quot;auto&quot;&gt;profile_health.skills.invalid_skills&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;A skipped file is harmless while nothing activates it. If a skill that is &lt;strong&gt;already in force&lt;/strong&gt;
stops loading (for example, you add an unknown key to its record), Spec Kitty refuses instead of
dropping it. &lt;code dir=&quot;auto&quot;&gt;charter activate&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; and the skill migrations report
&lt;code dir=&quot;auto&quot;&gt;activated skill &apos;&amp;#x3C;id&gt;&apos; is not available in any pack tier&lt;/code&gt;, followed by what the loader said, and
they delete nothing. Fix the record and run the command again.&lt;/p&gt;
&lt;h2 id=&quot;step-3-activate-it&quot;&gt;Step 3: Activate it&lt;/h2&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;charter&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;activate&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;skill&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;release-notes&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Output (abridged):&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;Activated: release-notes&lt;/span&gt;&lt;/div&gt;&lt;/div&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;Skill file synced: .claude/skills/acme-release-notes/SKILL.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;On disk, you now have &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;primary skill root&gt;/acme-release-notes/SKILL.md&lt;/code&gt; for each configured
tool:&lt;/p&gt;





























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Tools&lt;/th&gt;&lt;th&gt;Skill root&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Claude Code&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.claude/skills/&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Qwen Code&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.qwen/skills/&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Kilocode&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.kilocode/skills/&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Codex, Copilot, Gemini, Cursor, OpenCode, Windsurf, Vibe, Pi, Letta, Auggie, Kiro, Antigravity, LLxprt&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Amazon Q&lt;/td&gt;&lt;td&gt;none (Spec Kitty skips it)&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;In the shared &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; root the &lt;code dir=&quot;auto&quot;&gt;SKILL.md&lt;/code&gt; frontmatter carries only the Agent Skills
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;,
&lt;code dir=&quot;auto&quot;&gt;allowed-tools&lt;/code&gt;); any other key, such as &lt;code dir=&quot;auto&quot;&gt;argument-hint&lt;/code&gt;, is moved under &lt;code dir=&quot;auto&quot;&gt;metadata&lt;/code&gt;. The
&lt;code dir=&quot;auto&quot;&gt;.claude/skills/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.qwen/skills/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;.kilocode/skills/&lt;/code&gt; copies 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;/p&gt;
&lt;p&gt;Spec Kitty also records every file in &lt;code dir=&quot;auto&quot;&gt;.kittify/skills-manifest.json&lt;/code&gt;. That record is how it
later knows which files it owns. It never writes a pack skill to a user-global skill root.&lt;/p&gt;
&lt;p&gt;Things to know:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Activation and projection are two steps.&lt;/strong&gt; Spec Kitty records the activation first. If
projection then refuses (a missing namespace, say), the command exits with an error that says
&lt;code dir=&quot;auto&quot;&gt;The activation change is recorded&lt;/code&gt;. Fix the cause and run the same command again.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The first &lt;code dir=&quot;auto&quot;&gt;activate skill&lt;/code&gt; writes &lt;code dir=&quot;auto&quot;&gt;activated_skills&lt;/code&gt;.&lt;/strong&gt; While that key is absent, only the
org packs’ &lt;code dir=&quot;auto&quot;&gt;required_skills&lt;/code&gt; are in force. Your project-tier skill is not.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Spec Kitty keeps what it does not own.&lt;/strong&gt; A same-name directory that is not in the manifest is
left alone and reported as &lt;code dir=&quot;auto&quot;&gt;Skill file preserved&lt;/code&gt;. An empty one is projected into.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;step-4-check-the-result&quot;&gt;Step 4: Check the result&lt;/h2&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;p&gt;&lt;code dir=&quot;auto&quot;&gt;doctor skills&lt;/code&gt; exits 1 when it finds a problem with a pack skill. It reports five kinds of finding.
The first four name the pack source file. With &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt;, the same findings appear in a &lt;code dir=&quot;auto&quot;&gt;pack_skills&lt;/code&gt;
list. That key is additive: existing keys are unchanged.&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Finding&lt;/th&gt;&lt;th&gt;What it means&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;drift&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Someone edited the rendered &lt;code dir=&quot;auto&quot;&gt;SKILL.md&lt;/code&gt;. Spec Kitty keeps the edited copy.&lt;/td&gt;&lt;td&gt;Make the change in the pack source file instead. To drop the local edit, delete the copied file and run &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;stale&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The pack source changed after the copy was written.&lt;/td&gt;&lt;td&gt;Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt;. It refreshes the copy.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;missing&lt;/code&gt;&lt;/td&gt;&lt;td&gt;A pack skill is in force for a configured tool that accepts skill files, but it is not installed: it was never projected, or someone deleted the installed copy.&lt;/td&gt;&lt;td&gt;Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor skills --fix&lt;/code&gt;. It installs the copy. &lt;code dir=&quot;auto&quot;&gt;--fix&lt;/code&gt; lists each installed path under &lt;code dir=&quot;auto&quot;&gt;repaired_paths&lt;/code&gt; in the &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; output. &lt;code dir=&quot;auto&quot;&gt;--fix&lt;/code&gt; never repairs &lt;code dir=&quot;auto&quot;&gt;drift&lt;/code&gt;: it keeps your edited copy.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;orphaned&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The manifest lists a copy that the current pack no longer provides: the skill was removed or deactivated, or the namespace changed so the skill renders under a new name.&lt;/td&gt;&lt;td&gt;Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; to retire the old copy, or activate the skill again.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;unresolvable&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Spec Kitty could not resolve the pack skills in force, so it projected no pack skill and checked no installed copy for staleness or orphaning. The message gives the reason: a missing or invalid &lt;code dir=&quot;auto&quot;&gt;skill_namespace&lt;/code&gt;, a pack that does not load, two packs with the same skill id.&lt;/td&gt;&lt;td&gt;Fix the cause the message names, then run &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor skills&lt;/code&gt; again.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;doctor skills&lt;/code&gt; also fails with a &lt;code dir=&quot;auto&quot;&gt;no_tool_folder&lt;/code&gt; finding when none of the tool folders your
configured agents use exists (for example, no &lt;code dir=&quot;auto&quot;&gt;.claude/&lt;/code&gt; directory at all). The &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; output lists it
under a &lt;code dir=&quot;auto&quot;&gt;tool_folders&lt;/code&gt; key, with a &lt;code dir=&quot;auto&quot;&gt;message&lt;/code&gt; that names the folders. Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; to recreate
the configured folders, or &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent config remove &amp;#x3C;agent&gt;&lt;/code&gt; to drop a tool you no longer use.
&lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; also warns &lt;code dir=&quot;auto&quot;&gt;pack_skill_missing&lt;/code&gt; for a skill in force that is not installed.&lt;/p&gt;
&lt;p&gt;The rendered file is read-only by default. Edit the pack source, not the copy.&lt;/p&gt;
&lt;p&gt;The same cause also stops &lt;code dir=&quot;auto&quot;&gt;charter activate skill&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; (see the last
section). Fix it once and all three work again.&lt;/p&gt;
&lt;h2 id=&quot;step-5-deactivate-it&quot;&gt;Step 5: Deactivate it&lt;/h2&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;charter&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;deactivate&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;skill&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;release-notes&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;This retires the files that Spec Kitty wrote, and nothing else. It never deletes your pack
source files, a directory it does not own, or a copy you edited. It lists a kept copy as
&lt;code dir=&quot;auto&quot;&gt;Skill file preserved&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;After the last deactivation, &lt;code dir=&quot;auto&quot;&gt;activated_skills&lt;/code&gt; is an empty list, and an empty list means no
pack skill is in force. That includes any skill an org pack requires. To get the default back,
activate the skills you want, or remove the &lt;code dir=&quot;auto&quot;&gt;activated_skills&lt;/code&gt; key from the file that holds it
(&lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; unless your charter configuration lives in a separate &lt;code dir=&quot;auto&quot;&gt;charter.yaml&lt;/code&gt;).&lt;/p&gt;
&lt;h2 id=&quot;what-spec-kitty-upgrade-does-with-pack-skills&quot;&gt;What &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; does with pack skills&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; treats pack skills as part of the project’s skill inventory:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;It keeps the pack skills that are in force. It does not prune them.&lt;/li&gt;
&lt;li&gt;It refreshes a stale copy and retires an orphaned one.&lt;/li&gt;
&lt;li&gt;It keeps a copy you edited and reports it as &lt;code dir=&quot;auto&quot;&gt;drift&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;It writes again a copy that you deleted.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;If Spec Kitty cannot resolve the pack skills in force, the skill migrations that run report a
failure and change nothing. The error reads &lt;code dir=&quot;auto&quot;&gt;Pack skills could not be resolved: &amp;#x3C;reason&gt;&lt;/code&gt;. This applies only
to a project that has a pack skill in force. A project with none is not affected, even when an
org pack’s DRG fragment is damaged. Typical causes are a missing or invalid namespace, two skills
with the same rendered name, a skill record that no longer loads, an unreadable pack file, or a
damaged org pack DRG fragment. Fix the cause named in the reason, then run &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt;
again.&lt;/p&gt;
&lt;h2 id=&quot;share-the-skill-through-an-org-pack&quot;&gt;Share the skill through an org pack&lt;/h2&gt;
&lt;p&gt;An org pack works the same way, with two differences:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Put the files in the pack’s &lt;code dir=&quot;auto&quot;&gt;skills/&lt;/code&gt; directory (&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;pack&gt;/skills/&amp;#x3C;id&gt;.skill.yaml&lt;/code&gt;). Set
&lt;code dir=&quot;auto&quot;&gt;skill_namespace&lt;/code&gt; in the pack’s &lt;code dir=&quot;auto&quot;&gt;org-charter.yaml&lt;/code&gt; instead of the project config. When several
packs set it, the last non-empty value wins.&lt;/li&gt;
&lt;li&gt;List the ids in &lt;code dir=&quot;auto&quot;&gt;required_skills&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;org-charter.yaml&lt;/code&gt; to put a skill in force for every
project that registers the pack, without a &lt;code dir=&quot;auto&quot;&gt;charter activate&lt;/code&gt; step. Two sibling org packs must
not declare the same skill id.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;See &lt;a href=&quot;/architecture/org-doctrine-layer/&quot;&gt;Understanding the Org Layer of the Charter Offering&lt;/a&gt; for how a
project registers a pack.&lt;/p&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty-open-packs/blob/main/packs/internal/README.md&quot;&gt;Internal pack README&lt;/a&gt; — a worked org pack: the four &lt;code dir=&quot;auto&quot;&gt;kitty-*&lt;/code&gt; maintainer skills, each requiring the procedure that holds its rules.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/how-to/enable-the-internal-pack/&quot;&gt;How to enable the internal charter and skills&lt;/a&gt; — register the internal pack and project its &lt;code dir=&quot;auto&quot;&gt;kitty-*&lt;/code&gt; skills.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/doctrine-kinds/#skill&quot;&gt;Doctrine artifact kinds: Skill&lt;/a&gt; — what the kind is for.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/adr/3.x/2026-09-27-1-pack-skills-share-commands-through-charter-packs/&quot;&gt;ADR 2026-09-27-1&lt;/a&gt;
— the decision, and the ownership proof for the files Spec Kitty writes.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/how-to/create-a-doctrine-artifact/&quot;&gt;Create a doctrine artifact&lt;/a&gt; — the walkthrough for the other kinds.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
