Copy vs Symlink Skill Installation Methods in Agent-Skills: A Complete Guide

Agent-skills supports two distinct skill installation methods—copy and symlink—with automatic fallback from symlink to copy when filesystem permissions prevent link creation.

The tech-leads-club/agent-skills CLI provides flexible skill installation methods that determine how skill files are placed into an agent's working directory. Understanding the differences between copying and symlinking ensures you choose the right approach for development workflows, CI pipelines, and disk space management.

How Copy Installation Works

The copy method creates a complete duplicate of the skill's folder in the target location. According to the source code in libs/core/src/lib/services/installer.service.ts, the copySkillDirectory function (lines 55-62) handles this by recursively copying all skill files into the destination.

When you run the install command without the --symlink flag, the installer defaults to this method. Copy installation operates in two modes:

• copy-global: Copies the skill into the user-wide cache at ~/.cache/agent-skills/…
• copy-local: Copies the skill into the project-specific .agents/… folder

This method guarantees portability across all filesystems, including Windows environments where symlink creation requires elevated privileges.

How Symlink Installation Works

The symlink method creates a symbolic link that points to the original skill folder rather than duplicating files. The createSymlink function in libs/core/src/lib/services/installer.service.ts (lines 27-33) implements this by establishing a filesystem link to the source directory.

To activate this method, append the --symlink flag to your installation command. Similar to copy, symlink supports two modes:

• symlink-global: Creates a link pointing to the global cache, allowing multiple projects to share the same skill files
• symlink-local: Creates a link inside the project directory pointing to the original skill folder on disk

Symlink installations record method: 'symlink' in the lockfile, along with usedGlobalSymlink: true when global links are reused.

Key Differences Between Copy and Symlink

Aspect	Copy	Symlink
Disk usage	Creates full duplicates (higher space usage)	Points to source (minimal space usage)
File isolation	Changes to source do not affect installed copies	Changes to source immediately reflect in linked agents
Compatibility	Works on every filesystem including restricted Windows	Requires symlink permissions; fails on restricted CI runners
Performance	Slower for large skill trees due to copy operations	Near-instant regardless of skill size

Automatic Fallback When Symlinks Fail

The installer implements robust fallback logic for environments where symlink creation is prohibited. In libs/core/src/lib/services/installer.service.ts (lines 77-90), the code first attempts createSymlink. If this promise rejects due to permission errors, the installer automatically falls back to copySkillDirectory and records symlinkFailed: true in the lockfile result (lines 89-92).

This ensures installations never fail completely due to filesystem restrictions. The lockfile entry in libs/core/src/lib/services/lockfile.service.ts (lines 141-155) preserves this state, marking the installation with both the intended and actual methods used.

Global vs Local Installation Contexts

Both skill installation methods support global and local scopes, but the behavior differs significantly:

Copy installations:

• Global: Stores a dedicated copy in the system cache usable by any project
• Local: Stores a dedicated copy within the specific project directory

Symlink installations:

• Global: Creates a reference to the cached version, maximizing space efficiency across projects
• Local: Creates a reference to the original development source, ideal for iterating on skills in real-time

When to Use Each Installation Method

Choose copy when:

• Running in CI/CD pipelines with restricted permissions
• Working on Windows machines without administrator privileges
• You need isolated skill versions that won't change when the source updates
• Disk space is not a primary constraint

Choose symlink when:

• Developing skills locally and testing changes across multiple agents simultaneously
• Working with large skill repositories where duplication would waste significant space
• You have full filesystem permissions and want faster installation speeds

Prefer global symlinks (--global --symlink) when the same skill is used across multiple projects on the same machine, as this avoids redundant copies while maintaining a single source of truth in the global cache.

Inspecting Installation Methods in the Lockfile

After installation, verify the method used by examining the lockfile generated at libs/core/src/lib/services/lockfile.service.ts:

{
  "my-awesome-skill": {
    "name": "my-awesome-skill",
    "agent": ["cursor"],
    "method": "symlink",
    "usedGlobalSymlink": true
  }
}

If a symlink attempt failed and the system fell back to copy, the entry includes "symlinkFailed": true alongside the copy method indicator.

CLI Examples for Both Methods

Install using the default copy method:

# Local copy (default behavior)

agent-skills install --skill my-awesome-skill

# Global copy

agent-skills install --skill my-awesome-skill --global

Install using symlink method:

# Attempt symlink with automatic fallback to copy

agent-skills install --skill my-awesome-skill --symlink

# Global symlink for cross-project sharing

agent-skills install --skill my-awesome-skill --global --symlink

Summary

• Copy installation duplicates skill files via copySkillDirectory in installer.service.ts, ensuring maximum compatibility but consuming more disk space.
• Symlink installation references source files via createSymlink, saving space and enabling real-time updates but requiring appropriate filesystem permissions.
• The installer automatically falls back from symlink to copy when permissions are insufficient, recording symlinkFailed: true in the lockfile.
• Global installations cache skills in ~/.cache/agent-skills/, while local installations place them in project-specific .agents/ directories.
• Both methods are configured through the CLI in packages/cli/src/cli/install.ts and persisted via lockfile.service.ts.

Frequently Asked Questions

What happens if I use --symlink on a system that doesn't support symbolic links?

The installer catches the permission error in installer.service.ts (lines 89-92) and automatically executes a copy installation instead. The resulting lockfile entry contains "symlinkFailed": true to indicate that the fallback occurred, ensuring your skill is installed successfully regardless of filesystem limitations.

Does updating a skill source affect existing installations?

Only for symlink installations. When using symlink, changes to the original skill folder immediately propagate to all linked agents. When using copy, the skill remains isolated at the version installed until you explicitly reinstall or update, making copies safer for production stability.

How do I know which installation method was used for an existing skill?

Check the lockfile managed by lockfile.service.ts. Look for the method field which will be either "copy" or "symlink". Symlink entries may also include usedGlobalSymlink: true for global cache references, while failed symlinks that fell back to copy include symlinkFailed: true.

Which method should I use in CI/CD pipelines?

Use copy (the default) for CI/CD environments. Symlink creation often fails in containerized or restricted CI runners due to security policies. The copy method guarantees portable, reliable installations across all platforms without requiring elevated privileges or special filesystem capabilities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}