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

> Understand copy vs symlink skill installation in agent-skills. Learn when to use each and discover automatic fallback for seamless integration.

- Repository: [TechLeads.club 💎/agent-skills](https://github.com/tech-leads-club/agent-skills)
- Tags: how-to-guide
- Published: 2026-05-18

---

**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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/libs/core/src/lib/services/lockfile.service.ts):

```json
{
  "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:

```bash

# 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:

```bash

# 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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/packages/cli/src/cli/install.ts) and persisted via [`lockfile.service.ts`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/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`](https://github.com/tech-leads-club/agent-skills/blob/main/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.