How AgentSight shares versioned agent skills without copying them

The short answer

The bridge has three layers. AgentSight pins eunomia-bpf/agent-skills at a specific commit under.agents/sources/agent-skills. Its Bash or PowerShell wrapper initializes that submodule and calls the linker's script. The linker then creates one local link per valid skill directory under.agents/skills. Because the generated target directory is ignored, Git records the upstream revision but not machine-specific link objects.

This matters when the same maintainer workflow should be reusable across repositories without creating divergent copies. An upstream change does not silently modify an AgentSight checkout: the consumer's gitlink must move before a new skill-pack revision becomes part of the repository state.

The four pieces of the bridge

Pinning the pack is different from copying the pack

A copied skill directory loses its upstream identity unless the repository adds another synchronization convention. The AgentSight bridge uses Git's submodule object as that identity. At v1.0.30, the product tree points .agents/sources/agent-skills at commit 80b46492986e. A clone can therefore answer two separate questions: which skill pack was intended, and which local links have been generated from it.

The split also makes updates reviewable. Pulling the latest agent-skills repository by itself is not a product update. AgentSight only adopts a new shared pack when its committed gitlink changes. That keeps a maintainer workflow change closer to a dependency update than an invisible mutable global install.

The generated links are deliberately not committed

AgentSight's .gitignore excludes /.agents/skills/. The repository therefore commits the source location and synchronization entrypoints, not the output of linking on one developer's machine. This avoids checking in absolute paths, platform-specific reparse-point behavior, or a second copy of eachSKILL.md tree.

The Bash wrapper is intentionally small: initialize exactly the .agents/sources/agent-skillssubmodule, then run that pinned revision's scripts/link-skills.sh with the repository's.agents/skills directory as the destination. The policy for what counts as a skill therefore travels with the pinned source instead of being duplicated in the consumer wrapper.

The linker is conservative about existing paths

On Bash, only child directories that contain a SKILL.md are candidates. Before creating a link, the script checks the target path. If a real file or directory exists there, it exits withRefusing to replace real path. An existing symbolic link can be replaced, but an ordinary local directory cannot be silently converted into a shared skill.

The PowerShell implementation follows the same ownership rule with Windows filesystem semantics. A normal existing path is rejected. A reparse point that already targets the intended skill is left in place. A stale reparse point may be replaced. In Auto mode, Windows first tries a symbolic link and falls back to a directory junction when symlink creation is unavailable. The fallback changes the filesystem mechanism, not the canonical source directory.

What is actually in the pinned shared pack?

The revision used by AgentSight v1.0.30 contains seven reusable workflows. Six are general open-source maintainer workflows—agent-cli-tools, gh-workflow, oss-change-workflow,oss-issue-triage, oss-release-readiness, and project-bootstrap-workflow—and one is the organization-level eunomia-community-patrol workflow. The pack's README explicitly excludes skills tied to one consumer's content tree, publishing ledger, site paths, SEO operation, or repository-specific research workflow.

That exclusion is useful architecture, not housekeeping. A skill becomes shareable when its evidence and workflow contract make sense across consumers. A repository-specific skill should stay with the repository that owns its paths, data model, or publication semantics rather than being generalized only to reduce file count.

Do not confuse the shared bridge with AgentSight's repo-local prototype skills

AgentSight also has a committed skills/ directory for behavior-analysis prototypes such as semantic flamegraphs, interaction insights, skill evolution, system-friction analysis, and testing. Its own README describes those as repo-local prototypes for a possible shareable pack, not runtime code. The repository's .claude/skills link points at that local skills/ directory.

The v1.0.30 shared bridge is a separate path: .agents/sources/agent-skills is the pinned reusable source and .agents/skills is generated locally. Keeping those two mechanisms distinct prevents a release note about “shared skills” from being misread as “all AgentSight analysis skills are now installed globally” or “AgentSight runtime automatically executes these skills.” Neither claim is supported by the source.

A reproducible way to inspect the bridge

The useful verification is not “does a directory named skills exist?” Check the committed dependency, run the repository wrapper, and verify that each generated target resolves back into the pinned submodule. Also verify that the generated directory remains untracked. On a clean v1.0.30 checkout, the sequence is:

git submodule status .agents/sources/agent-skills
./scripts/sync-agent-skills.sh
find .agents/skills -maxdepth 1 -type l -print
readlink .agents/skills/oss-change-workflow
git status --short -- .agents/skills

Windows users can run scripts/sync-agent-skills.ps1 instead and inspect whether each target is a symbolic link or junction. Either representation is acceptable when it resolves to the pinned source. The final git status check should stay quiet for generated links because the directory is ignored.

When this pattern is useful—and when it is not

A pinned source plus generated links works well when several repositories should consume the same workflow definitions, updates need reviewable version boundaries, and users should edit one canonical copy instead of seven local clones. It is less useful when a consumer intentionally wants an independent fork, cannot use submodules, or needs to change the skill's assumptions to match repository-owned data and paths.

The broader lesson is to separate version ownership from local discovery. Git should record which reusable workflow version the repository depends on. Local setup should make that workflow visible to the agent without turning OS-specific links into source files. And synchronization should fail rather than overwrite a path whose ownership is ambiguous.

Related AgentSight evidence

If you are interested in how AgentSight observes the behavior that later feeds skill improvements, start with audit provenance and confidence. For a different kind of reusable evidence artifact, see how repository replay reconstructs file evolution. The shared-skills bridge itself is repository infrastructure: it makes reusable workflow definitions versioned and discoverable, but it does not create new runtime telemetry.