<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-04-08-3-global-skill-installation-per-project-symlinks/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-08-3-global-skill-installation-per-project-symlinks/</id>
  <title>ADR 3 (2026-04-08): Global Skill Installation with Per-Project Symlinks</title>
  <updated>2026-04-08T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-04-08-3-global-skill-installation-per-project-symlinks/"/>
  <summary>Skills live canonically under ~/.kittify/agent-skills/&lt;agent&gt;/ and projects reference them by symlink, with a file-copy fallback where symlinks are unavailable.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Superseded (2026-07-19):&lt;/strong&gt; the per-project &lt;strong&gt;symlink&lt;/strong&gt; wiring decided here is
replaced by copy delivery — absolute symlinks dangle in dev-containers and are
unreadable to sandboxed agent harnesses (#2412). The &lt;strong&gt;global canonical
install&lt;/strong&gt; half of this decision stands unchanged and is reaffirmed in
&lt;a href=&quot;/adr/3.x/2026-07-19-2-skill-projection-copies-not-symlinks/&quot;&gt;ADR 2026-07-19-2&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Skills are markdown files that extend agent capabilities — they encode domain-specific workflows, patterns, and shortcuts that agents invoke during mission execution. Examples include &lt;code dir=&quot;auto&quot;&gt;spec-kitty-git-workflow.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;spec-kitty-charter-doctrine.md&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;spec-kitty-implement-review.md&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Prior to this decision, skills were installed on a per-project basis during &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt;. Each project received its own copy of every skill file for every configured agent. The installation wrote files to &lt;code dir=&quot;auto&quot;&gt;.claude/commands/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.codex/prompts/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.github/prompts/&lt;/code&gt;, and so on within the project directory.&lt;/p&gt;
&lt;p&gt;This per-project model created several operational problems:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Upgrade burden.&lt;/strong&gt; When a skill file is updated in a new release of spec-kitty-cli, the developer must run &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; in every project to propagate the change. A developer with ten projects has ten separate upgrade operations. Missing any one of them means that project continues to use an outdated skill.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Disk duplication.&lt;/strong&gt; A developer with ten projects and 13 agents configured has up to 130 × (number of skill files) copies of identical markdown files spread across their filesystem.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Scope confusion.&lt;/strong&gt; Skills, like mission templates, are machine-level capabilities. They describe what the agent knows how to do on this developer’s machine, not anything specific to a given project. Installing them per-project conflates capability configuration with project configuration.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Double-prompt problem (interaction).&lt;/strong&gt; Per-project skill copies interact with the global installation to produce duplicate slash commands in AI tools (see ADR-F for the migration that addresses this interaction). The root cause is that skills are installed in both per-project directories and global agent command directories simultaneously.&lt;/p&gt;
&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;&lt;strong&gt;Single upgrade touch-point:&lt;/strong&gt; Upgrading skills should update all projects automatically.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Disk efficiency:&lt;/strong&gt; One copy of a skill per agent per machine, not N copies per project.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Alignment with global runtime model:&lt;/strong&gt; Skills are a machine-level capability; their canonical location should be machine-level (see ADR-A).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Practical compatibility:&lt;/strong&gt; Not all filesystems and developer environments support symlinks (e.g., some Windows configurations, network shares, certain container mounts).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option A: Global install to &lt;code dir=&quot;auto&quot;&gt;~/.kittify/agent-skills/&lt;/code&gt;, per-project symlinks (chosen)&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B: Per-project full copy (status quo)&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C: Symlink only, no copy fallback&lt;/strong&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option: Option A — Skills are installed canonically to &lt;code dir=&quot;auto&quot;&gt;~/.kittify/agent-skills/{agent}/&lt;/code&gt;. Per-project agent directories reference skills via symlinks, with a copy fallback for environments that do not support symlinks.&lt;/strong&gt;&lt;/p&gt;
&lt;h3 id=&quot;installation-target&quot;&gt;Installation Target&lt;/h3&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;plaintext&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/agent-skills/&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;claude/&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;spec-kitty-git-workflow.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 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;spec-kitty-charter-doctrine.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 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;spec-kitty-implement-review.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 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;/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;codex/&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;/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;opencode/&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;/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;spec-kitty init&lt;/code&gt; is responsible for populating these directories from the package-bundled skill sources (see ADR-B).&lt;/p&gt;
&lt;h3 id=&quot;per-project-wiring&quot;&gt;Per-Project Wiring&lt;/h3&gt;
&lt;p&gt;When a project directory references skills, it creates symlinks from its agent command directories into the global installation:&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;plaintext&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;.claude/commands/spec-kitty-git-workflow.md -&gt; ~/.kittify/agent-skills/claude/spec-kitty-git-workflow.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 filesystems where symlinks are not supported, the installer falls back to copying the file.&lt;/p&gt;
&lt;h3 id=&quot;known-current-limitation&quot;&gt;Known Current Limitation&lt;/h3&gt;
&lt;p&gt;The feature 076 implementation installs per-project skill wiring during &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; (a known gap from the intended architecture). This means skill files continue to be present in project agent directories for now. This ADR documents the intended architecture — global install is canonical, per-project is derived — and the per-project wiring will be moved to a dedicated per-project setup flow in a future feature. The double-prompt problem caused by this gap is addressed by the hardened command-globalization path that ships in &lt;code dir=&quot;auto&quot;&gt;3.2.0a4&lt;/code&gt; (see ADR-F).&lt;/p&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Upgrading skills requires a single &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; on the machine; all projects that symlink to global skills see the update immediately.&lt;/li&gt;
&lt;li&gt;Disk usage is proportional to the number of agents configured, not agents × projects.&lt;/li&gt;
&lt;li&gt;The machine-level / project-level boundary is reinforced.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Per-project setup (creating symlinks or copies) requires a wiring step that is currently bundled into init rather than into a dedicated per-project setup command. This will be addressed in a future feature.&lt;/li&gt;
&lt;li&gt;Symlink-based wiring can break if the global install is moved or deleted. Projects must detect broken symlinks and surface an actionable error.&lt;/li&gt;
&lt;li&gt;Copy fallback diverges from the global install when skills are upgraded; the fallback case requires a re-run of the wiring step to refresh.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The per-project agent command directories (&lt;code dir=&quot;auto&quot;&gt;.claude/commands/&lt;/code&gt;, etc.) continue to exist; their content is now derived from global skills rather than independent copies.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;Correct behavior is confirmed when: &lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; populates &lt;code dir=&quot;auto&quot;&gt;~/.kittify/agent-skills/{agent}/&lt;/code&gt; with all skill files; and a subsequent &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; on a project refreshes any stale skill references without losing project-local customizations. Integration tests cover both the symlink and copy-fallback paths.&lt;/p&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-a-global-install-with-per-project-symlinks-chosen&quot;&gt;Option A: Global install with per-project symlinks (chosen)&lt;/h3&gt;
&lt;p&gt;Skills live in &lt;code dir=&quot;auto&quot;&gt;~/.kittify/agent-skills/&lt;/code&gt;. Per-project agent directories contain symlinks (or copies as fallback) pointing to the global location.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;One upgrade point for all projects.&lt;/li&gt;
&lt;li&gt;Disk-efficient.&lt;/li&gt;
&lt;li&gt;Consistent with the global runtime model established in ADR-A.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Symlink creation must handle fallback.&lt;/li&gt;
&lt;li&gt;Broken symlinks require detection and user guidance.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-b-per-project-full-copy-status-quo&quot;&gt;Option B: Per-project full copy (status quo)&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty init&lt;/code&gt; copies skill files into each project’s agent command directories. Each project is independently up to date.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Self-contained: the project has everything it needs without relying on a global install.&lt;/li&gt;
&lt;li&gt;No symlink complexity or broken-link scenarios.&lt;/li&gt;
&lt;li&gt;Works on any filesystem.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;N copies of identical files across N projects.&lt;/li&gt;
&lt;li&gt;Upgrades require per-project &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; runs.&lt;/li&gt;
&lt;li&gt;Reinforces the conflation of machine-level and project-level state.&lt;/li&gt;
&lt;li&gt;Root cause of the double-prompt problem (local and global copies both visible to the agent).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; The upgrade burden and the double-prompt problem are both directly caused by this model. Neither can be fixed without changing the installation architecture.&lt;/p&gt;
&lt;h3 id=&quot;option-c-symlink-only-no-copy-fallback&quot;&gt;Option C: Symlink only, no copy fallback&lt;/h3&gt;
&lt;p&gt;Skills are always symlinks to the global installation. Copy fallback is not implemented.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Simpler implementation: no branching for symlink vs copy.&lt;/li&gt;
&lt;li&gt;Forces all environments to support symlinks (progressive enhancement).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Windows environments with symlink restrictions (requires elevated permissions or Developer Mode) would fail silently or with cryptic errors.&lt;/li&gt;
&lt;li&gt;Network-mounted project directories (common in remote development setups) may not support symlinks.&lt;/li&gt;
&lt;li&gt;Failing loudly on an unsupported filesystem is worse than copying.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; The potential failure modes on Windows and network filesystems affect a non-trivial portion of the user base. The copy fallback is a small implementation cost relative to the compatibility gain.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Spec:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;kitty-specs/076-init-command-overhaul/spec.md&lt;/code&gt; — FR-007 (skills installed to &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&lt;/code&gt;; per-project directories reference global install)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Related ADR:&lt;/strong&gt; ADR-A (2026-04-08-1) — Global &lt;code dir=&quot;auto&quot;&gt;~/.kittify/&lt;/code&gt; as machine-level runtime (establishes the global directory structure that skills live in)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Related ADR:&lt;/strong&gt; ADR-F (2026-04-08-6) — Global agent commands supersede per-project copies (migration that resolves the double-prompt problem caused by the current per-project gap)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Related ADR:&lt;/strong&gt; ADR-6 (2026-01-23-6) — Config-driven agent management&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Code locations:&lt;/strong&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/init.py&lt;/code&gt; — skill installation logic&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/shims/generator.py&lt;/code&gt; — shim/command file generation (distinct from skill installation)&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
