<?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-07-19-2-skill-projection-copies-not-symlinks/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-07-19-2-skill-projection-copies-not-symlinks/</id>
  <title>Skill projection delivers copies, not symlinks</title>
  <updated>2026-07-19T00: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-07-19-2-skill-projection-copies-not-symlinks/"/>
  <summary>Skill projection always copies files rather than symlinking a machine-global root, ending cross-project action-at-a-distance; stale symlinks convert on the next upgrade.</summary>
  <content type="html">&lt;span id=&quot;skill-projection-delivers-copies-not-symlinks&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted · &lt;strong&gt;Date:&lt;/strong&gt; 2026-07-19 · &lt;strong&gt;Supersedes:&lt;/strong&gt; the per-project wiring half of &lt;a href=&quot;/adr/3.x/2026-04-08-3-global-skill-installation-per-project-symlinks/&quot;&gt;ADR 2026-04-08-3&lt;/a&gt; (its global-canonical-install decision stands and is reaffirmed here) · &lt;strong&gt;Related:&lt;/strong&gt; &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2412&quot;&gt;#2412&lt;/a&gt;, &lt;a href=&quot;/adr/3.x/2026-07-07-1-ignored-surface-backfill-migration-pattern/&quot;&gt;ADR 2026-07-07-1&lt;/a&gt; (IGNORED-surface backfill pattern)&lt;/p&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;ADR 2026-04-08-3 established two things: canonical skills live in user-global roots (&lt;code dir=&quot;auto&quot;&gt;~/.kittify/agent-skills/&lt;/code&gt;, later &lt;code dir=&quot;auto&quot;&gt;~/.agents/skills/&lt;/code&gt; and per-agent homes), and per-project agent directories reference them &lt;strong&gt;via absolute symlinks&lt;/strong&gt;, with a copy fallback for filesystems that cannot symlink.&lt;/p&gt;
&lt;p&gt;Issue #2412 first surfaced the commit-side hazard of that wiring: an absolute symlink whose blob is &lt;code dir=&quot;auto&quot;&gt;/Users/&amp;#x3C;name&gt;/...&lt;/code&gt; is machine-local by construction, and nothing gitignored it. That half was fixed by PR #2423 (contract-registered &lt;code dir=&quot;auto&quot;&gt;IGNORED&lt;/code&gt; surfaces + backfill migration). The issue’s remaining ask — &lt;em&gt;should skills be delivered into the repo root as symlinks at all?&lt;/em&gt; — is what this ADR decides.&lt;/p&gt;
&lt;p&gt;The gitignore fix made symlinks safe to &lt;strong&gt;commit&lt;/strong&gt;. It did not make them safe to &lt;strong&gt;use&lt;/strong&gt;:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Dev-containers and remote mounts.&lt;/strong&gt; Mount the repo into a container or sync it to a remote box and every projected skill points at a home directory that does not exist there. The agent sees a dangling link; skills silently vanish with no diagnosable error.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Sandboxed agent harnesses.&lt;/strong&gt; Harnesses that restrict file reads to the repo root refuse to resolve a symlink whose target is outside it. The whole point of &lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; is to feed third-party agent tooling whose sandboxing spec-kitty does not control.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Global-root moves.&lt;/strong&gt; Uninstalling or relocating the CLI’s canonical root dangles every projected skill in every repo on the machine simultaneously, until each runs a repair.&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;Skills must be readable wherever the repo is readable.&lt;/strong&gt; The projection exists for third-party agents; delivery must not assume the reader can escape the project root or see the author’s &lt;code dir=&quot;auto&quot;&gt;$HOME&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Freshness must not regress.&lt;/strong&gt; The original symlink rationale — one upgrade touch-point — must be preserved in practice.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No per-project state divergence.&lt;/strong&gt; Projected files remain managed, regenerated artifacts, never hand-edited project content.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Minimal mechanism.&lt;/strong&gt; Prefer deleting a delivery mode over adding configuration for one.&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: Deliver copies, always (chosen)&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option B: Keep absolute symlinks (status quo, post-#2423)&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option C: Configurable delivery mode (symlink opt-in)&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 — &lt;code dir=&quot;auto&quot;&gt;_project_skill_file&lt;/code&gt; always delivers a copy; the symlink preference is removed rather than made optional.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;The freshness argument that justified symlinks in ADR 2026-04-08-3 is weaker than it looked: the installer re-projects the &lt;strong&gt;full skill set on every init/upgrade/repair run&lt;/strong&gt;, so copies refresh whenever the project itself is touched. What symlinks added on top was &lt;em&gt;cross-project action-at-a-distance&lt;/em&gt; — refreshing the global root silently changed the skill content of every repo on the machine, including repos whose generated command surfaces still matched an older CLI. Per-project refresh on that project’s own upgrade is the more correct semantic, not a compromise.&lt;/p&gt;
&lt;h3 id=&quot;mechanics&quot;&gt;Mechanics&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;skills/installer.py::_project_skill_file&lt;/code&gt; copies (&lt;code dir=&quot;auto&quot;&gt;shutil.copy2&lt;/code&gt;), never symlinks. A destination file whose content hash already matches the source is left untouched (idempotent re-runs); divergent content is archived to the migration backup root exactly as before.&lt;/li&gt;
&lt;li&gt;A pre-existing projection &lt;strong&gt;symlink&lt;/strong&gt; found at the destination is unlinked and replaced with a copy — conversion of existing projects happens organically on their next init/upgrade run, with &lt;strong&gt;no dedicated migration&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;skills/verifier.py::repair_skills&lt;/code&gt; always repairs to a copy and records &lt;code dir=&quot;auto&quot;&gt;delivery_mode: &quot;copy&quot;&lt;/code&gt;, healing legacy manifest entries as they are repaired. Verify-side tolerance for not-yet-converted symlinks remains.&lt;/li&gt;
&lt;li&gt;Copies inherit the canonical root’s read-only mode (&lt;code dir=&quot;auto&quot;&gt;copy2&lt;/code&gt; preserves it) — deliberate: the projection is not user-editable, matching the symlink-era semantics. Local edits are drift, detected and repairable as before.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;delivery_mode&lt;/code&gt; manifest field and its &lt;code dir=&quot;auto&quot;&gt;&quot;symlink&quot;&lt;/code&gt; value remain readable for pre-conversion manifests; new entries are always &lt;code dir=&quot;auto&quot;&gt;&quot;copy&quot;&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&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;Projected skills work in dev-containers, remote mounts, and repo-root-restricted sandboxes.&lt;/li&gt;
&lt;li&gt;A global-root move no longer breaks existing projects; their copies keep working until the next refresh.&lt;/li&gt;
&lt;li&gt;Net code deletion: the verifier’s symlink repair branch and its global-root resync helper are gone.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;A global-root refresh no longer propagates to a project until that project’s next init/upgrade/repair run.&lt;/li&gt;
&lt;li&gt;Duplicate markdown bytes per project (negligible at skill-pack scale).&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.agents/skills/&lt;/code&gt; and friends remain &lt;code dir=&quot;auto&quot;&gt;IGNORED&lt;/code&gt; state surfaces (#2423): copies are still per-machine regenerated content, not project content.&lt;/li&gt;
&lt;/ul&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-b-keep-absolute-symlinks&quot;&gt;Option B: Keep absolute symlinks&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; instant cross-project freshness; zero migration motion.
&lt;strong&gt;Cons:&lt;/strong&gt; dangles in containers/remote mounts; unreadable to repo-root sandboxes; global-root moves break every repo at once; the failure mode is always &lt;em&gt;silent&lt;/em&gt; skill absence.
&lt;strong&gt;Why rejected:&lt;/strong&gt; the projection’s consumers are exactly the tools most likely to run containerized or sandboxed.&lt;/p&gt;
&lt;h3 id=&quot;option-c-configurable-delivery-mode&quot;&gt;Option C: Configurable delivery mode&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt; preserves symlink freshness for users who want it.
&lt;strong&gt;Cons:&lt;/strong&gt; a config knob, two persistent code paths, and doc/test surface for a mode whose only benefit is marginal freshness; the hazard cases are environmental, not preferential — the user in a dev-container did not choose to be there.
&lt;strong&gt;Why rejected:&lt;/strong&gt; minimal-mechanism driver; nobody should have to configure their skills to be readable.&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;Issue:&lt;/strong&gt; &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2412&quot;&gt;#2412&lt;/a&gt; — ask 3 (asks 1–2 landed via PR #2423)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Code locations:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/skills/installer.py::_project_skill_file&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/skills/verifier.py::repair_skills&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Superseded wiring:&lt;/strong&gt; &lt;a href=&quot;/adr/3.x/2026-04-08-3-global-skill-installation-per-project-symlinks/&quot;&gt;ADR 2026-04-08-3&lt;/a&gt; — the global canonical install target it defines is unchanged&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
